An MCP server exposing your local iMessage history (macOS, read-only).
Project description
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file imessage_mcp-0.1.1.tar.gz.
File metadata
- Download URL: imessage_mcp-0.1.1.tar.gz
- Upload date:
- Size: 7.0 kB
- Tags: Source
- Uploaded using 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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
dc88a70026914f66709159bf6b11682bf1930ae02c97129dc8ac09eb3ad6b923
|
|
| MD5 |
9f2acd04e5dd8b4dc850d4739bd48be7
|
|
| BLAKE2b-256 |
ed0e4244475846efd5d99780c37cbadb190e9d2e394cf90dc089992951f5ff2c
|
File details
Details for the file imessage_mcp-0.1.1-py3-none-any.whl.
File metadata
- Download URL: imessage_mcp-0.1.1-py3-none-any.whl
- Upload date:
- Size: 9.8 kB
- Tags: Python 3
- Uploaded using 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}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
fef489c3c98df38217a4c224a9a48662cfc5ce5b11e20263efd9faa438991511
|
|
| MD5 |
e90271c51f6ed35add3836c7a6c659ff
|
|
| BLAKE2b-256 |
8a24588493de9abe86aee8e5ba1a3124d8dfd5180aa71ec1d69c2446ba21db60
|
