imessage-mcp 0.1.0__tar.gz

imessage_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.3
+Name: imessage-mcp
+Version: 0.1.0
+Summary: An MCP server exposing your local iMessage history (macOS, read-only).
+Keywords: mcp,imessage,macos,claude,llm
+Author: moritzhwnr
+Author-email: moritzhwnr <moritz.hawener@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Requires-Dist: mcp[cli]>=1.27.1
+Requires-Dist: rich>=14.0.0
+Requires-Dist: typer>=0.25.1
+Requires-Dist: uvicorn>=0.47.0
+Requires-Dist: starlette>=1.0.0
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/yourname/imessage-mcp
+Project-URL: Repository, https://github.com/yourname/imessage-mcp
+Project-URL: Issues, https://github.com/yourname/imessage-mcp/issues
+Description-Content-Type: text/markdown
+
+# imessage-mcp
+
+A read-only [MCP](https://modelcontextprotocol.io) server exposing your macOS iMessage history to any MCP-capable AI (Claude Desktop, Cursor, Poke, etc.).
+
+**100% local.** Your messages never leave your Mac. This package has zero external dependencies — no signup, no hosted service. Just install, grant Full Disk Access, run.
+
+## Install
+
+```bash
+uv tool install imessage-mcp
+```
+
+(Requires Python 3.13+ and `uv`. Install `uv` from <https://docs.astral.sh/uv/>.)
+
+## Quickstart
+
+```bash
+imessage-mcp setup           # opens the macOS Full Disk Access pane
+imessage-mcp serve           # MCP server on http://127.0.0.1:8765/mcp
+```
+
+Or expose it over the internet via a [Cloudflare Quick Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/):
+
+```bash
+brew install cloudflared
+imessage-mcp serve --public  # prints a *.trycloudflare.com URL + bearer token
+```
+
+The bearer token lives at `~/.config/imessage-mcp/token` (chmod 600). Rotate with `imessage-mcp token --rotate`.
+
+## Tools exposed via MCP
+
+| Tool | Purpose |
+|---|---|
+| `list_chats(limit)` | Most recent conversations |
+| `read_messages(chat_id, limit)` | Messages in a chat, oldest first |
+| `search_messages(query, limit)` | Substring search across all chats |
+
+## Want a stable broker URL across restarts?
+
+Cloudflare Quick Tunnels get a new hostname on every launch. If you want a stable URL (and an account-style flow with signup/login), install [`imessage-bridge`](https://pypi.org/project/imessage-bridge/) — a separate package that adds those features on top of this one via a hosted broker.
+
+## License
+
+MIT

imessage_mcp-0.1.0/README.md

@@ -0,0 +1,45 @@
+# imessage-mcp
+
+A read-only [MCP](https://modelcontextprotocol.io) server exposing your macOS iMessage history to any MCP-capable AI (Claude Desktop, Cursor, Poke, etc.).
+
+**100% local.** Your messages never leave your Mac. This package has zero external dependencies — no signup, no hosted service. Just install, grant Full Disk Access, run.
+
+## Install
+
+```bash
+uv tool install imessage-mcp
+```
+
+(Requires Python 3.13+ and `uv`. Install `uv` from <https://docs.astral.sh/uv/>.)
+
+## Quickstart
+
+```bash
+imessage-mcp setup           # opens the macOS Full Disk Access pane
+imessage-mcp serve           # MCP server on http://127.0.0.1:8765/mcp
+```
+
+Or expose it over the internet via a [Cloudflare Quick Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/):
+
+```bash
+brew install cloudflared
+imessage-mcp serve --public  # prints a *.trycloudflare.com URL + bearer token
+```
+
+The bearer token lives at `~/.config/imessage-mcp/token` (chmod 600). Rotate with `imessage-mcp token --rotate`.
+
+## Tools exposed via MCP
+
+| Tool | Purpose |
+|---|---|
+| `list_chats(limit)` | Most recent conversations |
+| `read_messages(chat_id, limit)` | Messages in a chat, oldest first |
+| `search_messages(query, limit)` | Substring search across all chats |
+
+## Want a stable broker URL across restarts?
+
+Cloudflare Quick Tunnels get a new hostname on every launch. If you want a stable URL (and an account-style flow with signup/login), install [`imessage-bridge`](https://pypi.org/project/imessage-bridge/) — a separate package that adds those features on top of this one via a hosted broker.
+
+## License
+
+MIT

imessage_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "imessage-mcp"
+version = "0.1.0"
+description = "An MCP server exposing your local iMessage history (macOS, read-only)."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "moritzhwnr", email = "moritz.hawener@gmail.com" },
+]
+requires-python = ">=3.13"
+dependencies = [
+    "mcp[cli]>=1.27.1",
+    "rich>=14.0.0",
+    "typer>=0.25.1",
+    "uvicorn>=0.47.0",
+    "starlette>=1.0.0",
+]
+keywords = ["mcp", "imessage", "macos", "claude", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS :: MacOS X",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Chat",
+]
+
+[project.urls]
+Homepage = "https://github.com/yourname/imessage-mcp"
+Repository = "https://github.com/yourname/imessage-mcp"
+Issues = "https://github.com/yourname/imessage-mcp/issues"
+
+[project.scripts]
+imessage-mcp = "imessage_mcp.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.2,<0.12.0"]
+build-backend = "uv_build"

imessage_mcp-0.1.0/src/imessage_mcp/__init__.py

@@ -0,0 +1,28 @@
+"""imessage-mcp — MCP server exposing local iMessage queries.
+
+Public API for downstream packages (like imessage-bridge) to import:
+  - `app`              — the Typer CLI app, extendable with @app.command()
+  - `mcp`              — the FastMCP instance with our tools registered
+  - `serve_mcp(...)`   — start the HTTP server (lower level, used by serve cmd)
+  - `spawn_cloudflared(...)` — start a Quick Tunnel subprocess
+  - `print_config_panel(...)` — render the Claude-Desktop-style JSON
+  - `CONFIG_DIR`, `TOKEN_FILE`
+  - `load_or_create_token(...)`
+"""
+
+from imessage_mcp.cli import app, main
+from imessage_mcp.config import CONFIG_DIR, TOKEN_FILE, load_or_create_token
+from imessage_mcp.server import mcp, serve_mcp
+from imessage_mcp.tunnel import print_config_panel, spawn_cloudflared
+
+__all__ = [
+    "app",
+    "main",
+    "mcp",
+    "serve_mcp",
+    "spawn_cloudflared",
+    "print_config_panel",
+    "CONFIG_DIR",
+    "TOKEN_FILE",
+    "load_or_create_token",
+]

imessage_mcp-0.1.0/src/imessage_mcp/_imessage.py

@@ -0,0 +1,27 @@
+"""macOS iMessage database access. Read-only, internal to the package.
+
+The chat.db file is a SQLite database macOS uses for Messages.app. We open
+it read-only (uri=mode=ro) to be safe against accidental writes. Timestamps
+in the DB are "Apple epoch" — nanoseconds since 2001-01-01 UTC.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+CHAT_DB = Path.home() / "Library" / "Messages" / "chat.db"
+APPLE_EPOCH = datetime(2001, 1, 1, tzinfo=timezone.utc)
+
+
+def open_db() -> sqlite3.Connection:
+    """Open chat.db read-only. Caller handles the FileNotFoundError / permission error."""
+    if not CHAT_DB.exists():
+        raise FileNotFoundError(f"chat.db not found at {CHAT_DB}")
+    return sqlite3.connect(f"file:{CHAT_DB}?mode=ro", uri=True)
+
+
+def apple_ts_to_dt(ts: int) -> datetime:
+    """Apple's nanosecond timestamp → datetime."""
+    return APPLE_EPOCH + timedelta(seconds=ts / 1_000_000_000)

imessage_mcp-0.1.0/src/imessage_mcp/cli.py

@@ -0,0 +1,111 @@
+"""Typer CLI for imessage-mcp — `serve`, `setup`, `token`.
+
+This is the standalone open-core CLI. No broker, no signup. Power users who
+don't want a third-party service install just this package.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from typing import Annotated
+from urllib.parse import urlparse
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from imessage_mcp._imessage import CHAT_DB
+from imessage_mcp.config import TOKEN_FILE, load_or_create_token
+from imessage_mcp.server import allow_tunnel_host, serve_mcp
+from imessage_mcp.tunnel import print_config_panel, spawn_cloudflared
+
+out = Console()
+err = Console(stderr=True)
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8765
+
+app = typer.Typer(
+    no_args_is_help=True,
+    help="MCP server exposing your local iMessage history (read-only).",
+)
+
+
+@app.command()
+def serve(
+    host: Annotated[
+        str, typer.Option(help="Bind address. Keep 127.0.0.1 unless you know why.")
+    ] = DEFAULT_HOST,
+    port: Annotated[int, typer.Option(help="TCP port.")] = DEFAULT_PORT,
+    public: Annotated[
+        bool,
+        typer.Option("--public", help="Expose via a cloudflared Quick Tunnel."),
+    ] = False,
+    rotate_token: Annotated[
+        bool, typer.Option("--rotate-token", help="Generate a fresh bearer token first.")
+    ] = False,
+) -> None:
+    """Run the MCP server (locally, or publicly via cloudflared with --public)."""
+    if not CHAT_DB.exists():
+        err.print(f"[red]chat.db not found at {CHAT_DB}[/red]")
+        err.print("Run [cyan]imessage-mcp setup[/cyan] to grant Full Disk Access.")
+        raise typer.Exit(code=1)
+
+    token = load_or_create_token(rotate=rotate_token)
+    local_url = f"http://{host}:{port}"
+    print_config_panel(local_url, token, public=False)
+
+    tunnel_proc: subprocess.Popen | None = None
+    if public:
+        def on_url(url: str) -> None:
+            allow_tunnel_host(urlparse(url).netloc, url)
+            print_config_panel(url, token, public=True)
+
+        tunnel_proc = spawn_cloudflared(local_url, on_url=on_url)
+        out.print("[dim]Waiting for cloudflared to establish the tunnel...[/dim]")
+
+    try:
+        serve_mcp(host=host, port=port, token=token)
+    finally:
+        if tunnel_proc is not None and tunnel_proc.poll() is None:
+            tunnel_proc.terminate()
+            try:
+                tunnel_proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                tunnel_proc.kill()
+
+
+@app.command()
+def setup() -> None:
+    """Open System Settings to grant Full Disk Access to your terminal."""
+    pane = "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"
+    subprocess.run(["open", pane], check=True)
+    out.print(
+        Panel(
+            "[bold]Full Disk Access[/bold] pane opened.\n"
+            "1. Click [cyan]+[/cyan] and add your terminal app.\n"
+            "2. Toggle it [green]on[/green].\n"
+            "3. [bold]Fully quit[/bold] the terminal (Cmd+Q) and reopen it.\n"
+            "4. Run [cyan]imessage-mcp serve[/cyan] to verify.",
+            border_style="cyan",
+        )
+    )
+
+
+@app.command()
+def token(
+    rotate: Annotated[
+        bool, typer.Option("--rotate", help="Generate a new token, replacing the old.")
+    ] = False,
+) -> None:
+    """Print the local bearer token (or rotate it)."""
+    t = load_or_create_token(rotate=rotate)
+    out.print(t)
+    if rotate:
+        err.print(
+            "[yellow]Rotated — any connected clients will start failing 401.[/yellow]"
+        )
+
+
+def main() -> None:
+    app()

imessage_mcp-0.1.0/src/imessage_mcp/config.py

@@ -0,0 +1,24 @@
+"""Config paths + local bearer token management."""
+
+from __future__ import annotations
+
+import secrets
+from pathlib import Path
+
+CONFIG_DIR = Path.home() / ".config" / "imessage-mcp"
+TOKEN_FILE = CONFIG_DIR / "token"
+
+
+def load_or_create_token(rotate: bool = False) -> str:
+    """Return the local bearer token, generating it on first run.
+
+    `secrets.token_urlsafe` gives 32 bytes of entropy as URL-safe base64 —
+    plenty for a personal API. chmod 600 = owner-only, ~/.ssh convention.
+    """
+    if TOKEN_FILE.exists() and not rotate:
+        return TOKEN_FILE.read_text().strip()
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    token = secrets.token_urlsafe(32)
+    TOKEN_FILE.write_text(token)
+    TOKEN_FILE.chmod(0o600)
+    return token

imessage_mcp-0.1.0/src/imessage_mcp/server.py

@@ -0,0 +1,180 @@
+"""FastMCP server + tools + bearer auth.
+
+This is the actual MCP service. The `serve_mcp` helper is the lower-level
+entry point that downstream packages (imessage-bridge) reuse — the Typer
+`serve` command just calls it.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from typing import Any
+
+import typer
+import uvicorn
+from mcp.server.fastmcp import FastMCP
+from rich.console import Console
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import JSONResponse
+
+from imessage_mcp._imessage import apple_ts_to_dt, open_db
+
+out = Console()
+err = Console(stderr=True)
+
+mcp = FastMCP("imessage")
+
+
+# ---------- bearer auth middleware ----------
+
+
+class BearerAuthMiddleware(BaseHTTPMiddleware):
+    """ASGI middleware that 401s anything without `Authorization: Bearer <token>`."""
+
+    def __init__(self, app, token: str) -> None:
+        super().__init__(app)
+        self._expected = f"Bearer {token}"
+
+    async def dispatch(self, request, call_next):
+        if request.headers.get("Authorization") != self._expected:
+            return JSONResponse({"error": "unauthorized"}, status_code=401)
+        return await call_next(request)
+
+
+# ---------- helper for tool error handling ----------
+
+
+def _safe_open_db() -> sqlite3.Connection:
+    """Translate DB access errors into MCP-friendly errors."""
+    try:
+        return open_db()
+    except FileNotFoundError as e:
+        raise RuntimeError(str(e)) from e
+    except sqlite3.OperationalError as e:
+        raise RuntimeError(
+            f"Cannot open chat.db: {e}. The process running imessage-mcp "
+            "probably lacks Full Disk Access. Run `imessage-mcp setup`."
+        ) from e
+
+
+# ---------- MCP tools ----------
+
+
+@mcp.tool()
+def list_chats(limit: int = 20) -> list[dict]:
+    """List the most recent iMessage conversations.
+
+    Args:
+        limit: How many chats to return (default 20).
+
+    Returns: list of {chat_id, who, last_message_at}, newest first.
+    """
+    conn = _safe_open_db()
+    rows = conn.execute(
+        """
+        SELECT c.ROWID, COALESCE(NULLIF(c.display_name, ''), h.id, '?'), MAX(m.date)
+        FROM chat c
+        JOIN chat_message_join cmj ON cmj.chat_id = c.ROWID
+        JOIN message m ON m.ROWID = cmj.message_id
+        LEFT JOIN chat_handle_join chj ON chj.chat_id = c.ROWID
+        LEFT JOIN handle h ON h.ROWID = chj.handle_id
+        GROUP BY c.ROWID ORDER BY MAX(m.date) DESC LIMIT ?
+        """,
+        (limit,),
+    ).fetchall()
+    return [
+        {
+            "chat_id": cid,
+            "who": who,
+            "last_message_at": apple_ts_to_dt(ts).astimezone().isoformat(),
+        }
+        for cid, who, ts in rows
+    ]
+
+
+@mcp.tool()
+def read_messages(chat_id: int, limit: int = 30) -> list[dict]:
+    """Read recent messages from a specific chat, oldest first.
+
+    Args:
+        chat_id: The chat ID (from list_chats).
+        limit: How many recent messages (default 30).
+    """
+    conn = _safe_open_db()
+    rows = conn.execute(
+        """
+        SELECT m.date, m.is_from_me, COALESCE(m.text, '')
+        FROM message m
+        JOIN chat_message_join cmj ON cmj.message_id = m.ROWID
+        WHERE cmj.chat_id = ?
+        ORDER BY m.date DESC LIMIT ?
+        """,
+        (chat_id, limit),
+    ).fetchall()
+    return [
+        {
+            "at": apple_ts_to_dt(ts).astimezone().isoformat(),
+            "from": "me" if is_me else "them",
+            "text": text,
+        }
+        for ts, is_me, text in reversed(rows)
+    ]
+
+
+@mcp.tool()
+def search_messages(query: str, limit: int = 30) -> list[dict]:
+    """Substring-search message text across all chats (case-insensitive).
+
+    Args:
+        query: The substring to search for.
+        limit: Max matches (default 30).
+    """
+    conn = _safe_open_db()
+    rows = conn.execute(
+        """
+        SELECT m.date, m.is_from_me, COALESCE(m.text, ''), cmj.chat_id,
+               COALESCE(NULLIF(c.display_name, ''), h.id, '?')
+        FROM message m
+        JOIN chat_message_join cmj ON cmj.message_id = m.ROWID
+        JOIN chat c ON c.ROWID = cmj.chat_id
+        LEFT JOIN chat_handle_join chj ON chj.chat_id = c.ROWID
+        LEFT JOIN handle h ON h.ROWID = chj.handle_id
+        WHERE m.text LIKE ? COLLATE NOCASE
+        ORDER BY m.date DESC LIMIT ?
+        """,
+        (f"%{query}%", limit),
+    ).fetchall()
+    return [
+        {
+            "at": apple_ts_to_dt(ts).astimezone().isoformat(),
+            "from": "me" if is_me else "them",
+            "text": text,
+            "chat_id": cid,
+            "who": who,
+        }
+        for ts, is_me, text, cid, who in rows
+    ]
+
+
+# ---------- server runner ----------
+
+
+def serve_mcp(host: str, port: int, token: str) -> None:
+    """Start the FastMCP HTTP server with bearer auth (blocks until stopped).
+
+    Extracted so downstream packages can run the same server while wrapping
+    the orchestration around it (e.g. broker registration in imessage-bridge).
+    """
+    asgi_app = mcp.streamable_http_app()
+    asgi_app.add_middleware(BearerAuthMiddleware, token=token)
+    uvicorn.run(asgi_app, host=host, port=port, log_level="info")
+
+
+def allow_tunnel_host(host: str, origin_url: str) -> None:
+    """Allow a runtime-discovered host through FastMCP's DNS rebinding check.
+
+    Used by the tunnel watcher when cloudflared comes up. The settings list
+    is read per-request, so adding to it at runtime takes effect immediately.
+    """
+    mcp.settings.transport_security.allowed_hosts.append(host)
+    mcp.settings.transport_security.allowed_origins.append(origin_url)

imessage_mcp-0.1.0/src/imessage_mcp/tunnel.py

@@ -0,0 +1,100 @@
+"""cloudflared subprocess + the config-panel renderer.
+
+Exported so imessage-bridge can reuse both: spawn the same tunnel, then
+print its own broker-aware config panel instead of the local one.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+import threading
+from typing import Callable
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+out = Console()
+err = Console(stderr=True)
+
+# Cloudflare Quick Tunnel hostnames look like https://<slug>.trycloudflare.com .
+TRYCLOUDFLARE_URL_RE = re.compile(r"https://[a-z0-9-]+\.trycloudflare\.com")
+
+
+def spawn_cloudflared(
+    local_url: str, on_url: Callable[[str], None]
+) -> subprocess.Popen:
+    """Start `cloudflared tunnel` and call `on_url(public_url)` once detected.
+
+    Notes:
+      - `cloudflared` must be on PATH. shutil.which() is the portable way.
+      - cloudflared logs to stderr → merge with stdout so we read one stream.
+      - bufsize=1 = line-buffered (Python's 4KB default would delay 30s).
+      - The watcher is a daemon thread, so it dies with the process.
+    """
+    if shutil.which("cloudflared") is None:
+        err.print("[red]cloudflared not found on PATH.[/red]")
+        err.print("Install it: [cyan]brew install cloudflared[/cyan]")
+        raise typer.Exit(code=1)
+
+    proc = subprocess.Popen(
+        ["cloudflared", "tunnel", "--url", local_url, "--no-autoupdate"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1,
+    )
+
+    def watch() -> None:
+        seen = False
+        assert proc.stdout is not None
+        for line in iter(proc.stdout.readline, ""):
+            if not seen:
+                m = TRYCLOUDFLARE_URL_RE.search(line)
+                if m:
+                    seen = True
+                    on_url(m.group(0))
+
+    threading.Thread(target=watch, daemon=True).start()
+    return proc
+
+
+def print_config_panel(public_url: str, token: str, *, public: bool) -> None:
+    """Render the copy-pasteable Claude Desktop config block.
+
+    `public=True` styles the panel as a public tunnel warning (yellow + a
+    "rotate if you leak it" reminder). `public=False` is cyan/local-only.
+    """
+    config_snippet = json.dumps(
+        {
+            "mcpServers": {
+                "imessage": {
+                    "url": f"{public_url}/mcp",
+                    "headers": {"Authorization": f"Bearer {token}"},
+                }
+            }
+        },
+        indent=2,
+    )
+    title = "imessage-mcp (PUBLIC via cloudflared)" if public else "imessage-mcp"
+    border = "yellow" if public else "cyan"
+    warning = (
+        "\n[yellow]⚠ Anyone with this URL + token can read your messages. "
+        "Rotate the token if you leak it.[/yellow]\n"
+        if public
+        else ""
+    )
+    out.print(
+        Panel(
+            f"[bold]{public_url}/mcp[/bold]\n"
+            f"[dim]Token saved to ~/.config/imessage-mcp/token[/dim]\n"
+            f"{warning}\n"
+            "Add to Claude Desktop's [cyan]claude_desktop_config.json[/cyan]:\n"
+            f"[green]{config_snippet}[/green]",
+            title=title,
+            border_style=border,
+        )
+    )