imessage-cli

A monorepo of three Python packages and a Next.js broker that turn your local iMessage history into something an MCP-capable AI (Claude, Cursor, Poke, …) can read — and optionally reply through — without your messages ever leaving your Mac.

Packages (published to PyPI)

Package	Install	What it does
imessage-mcp	uv tool install imessage-mcp	Read-only MCP server for your iMessage DB. No hosted service.
imessage-mcp-send	uv tool install imessage-mcp-send	Adds a send_message tool. Irreversible writes.
imessage-bridge	uv tool install imessage-bridge	Connected CLI with account-managed API keys and a stable broker URL.

Each package has its own README inside packages/<name>/.

Architecture

                Claude / Poke / Cursor  (MCP client)
                          │
                          │  Bearer <api_key>
                          ▼
              Next.js broker (backend/)      ◀── Supabase auth + Postgres
                          │  Bearer <tunnel_token>
                          ▼
              *.trycloudflare.com tunnel
                          │
                          ▼
              imessage-mcp on your Mac        ◀── chat.db (read-only)

The broker is plumbing — your messages never leave your Mac.

Repository layout

packages/imessage-mcp/         ← published: read-only MCP server
packages/imessage-mcp-send/    ← published: optional send_message tool
packages/imessage-bridge/      ← published: connected CLI for the broker
backend/                       ← Next.js + Supabase broker (not published)
src/imessage_cli/              ← legacy local-only tools (imessage-cli, imessage-ai)

The workspace is a uv workspace; packages share a single venv during dev.

Development setup

git clone https://github.com/moritzhwnr/imessage-cli
cd imessage-cli
uv sync                                 # installs all three packages + legacy CLIs in editable mode
uv run imessage-mcp --help
uv run imessage-bridge --help

For the broker:

cd backend
cp .env.local.example .env.local        # fill in Supabase URL + service-role key + encryption key
npm install
npm run dev                             # http://localhost:3000

See backend/supabase/migrations/0001_init.sql for the database schema and backend/.env.local.example for the required env vars.

License

MIT — see LICENSE.