imessage-mcp
A read-only MCP 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
uv tool install imessage-mcp
(Requires Python 3.13+ and uv. Install uv from https://docs.astral.sh/uv/.)
Quickstart
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:
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 — a separate package that adds those features on top of this one via a hosted broker.
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for imessage-mcp 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| imessage_mcp-0.1.1.tar.gz | 7.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| imessage_mcp-0.1.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 16.9 kB
Release files / imessage_mcp-0.1.1.tar.gz
| Download URL | imessage_mcp-0.1.1.tar.gz |
|---|---|
| Size | 7.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dc88a70026914f66709159bf6b11682bf1930ae02c97129dc8ac09eb3ad6b923
|
|
BLAKE2b-256 checksum How to use checksums |
ed0e4244475846efd5d99780c37cbadb190e9d2e394cf90dc089992951f5ff2c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.2 {"installer":{"name":"uv","version":"0.11.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / imessage_mcp-0.1.1-py3-none-any.whl
| Download URL | imessage_mcp-0.1.1-py3-none-any.whl |
|---|---|
| Size | 9.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fef489c3c98df38217a4c224a9a48662cfc5ce5b11e20263efd9faa438991511
|
|
BLAKE2b-256 checksum How to use checksums |
8a24588493de9abe86aee8e5ba1a3124d8dfd5180aa71ec1d69c2446ba21db60
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.2 {"installer":{"name":"uv","version":"0.11.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
