{"_id":"@daveremy/imessage-mcp","name":"@daveremy/imessage-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@daveremy/imessage-mcp","version":"0.1.0","description":"MCP server for reading and sending iMessages from Claude Code","type":"module","main":"dist/mcp.js","bin":{"imessage-mcp":"dist/cli.js"},"scripts":{"build":"tsc","dev":"tsx src/mcp.ts","test":"tsx --test src/__tests__/*.test.ts","prepack":"npm run build"},"os":["darwin"],"keywords":["imessage","mcp","claude","messages","macos"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/daveremy/imessage-mcp.git"},"engines":{"node":">=22.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.1","glob":"^11.0.2","zod":"^3.25.67"},"devDependencies":{"@types/node":"^22.15.30","tsx":"^4.19.4","typescript":"^5.8.3"},"gitHead":"42ba8b63c2af75a980e6f7378af14b6a334d2d44","types":"./dist/mcp.d.ts","_id":"@daveremy/imessage-mcp@0.1.0","bugs":{"url":"https://github.com/daveremy/imessage-mcp/issues"},"homepage":"https://github.com/daveremy/imessage-mcp#readme","_nodeVersion":"25.8.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-NSLEJjFu4MoNQGKCCWEfkCaOg1ZR5k4iwsKw3rWAw9OVHJfP9YvNaEQ15ui+o9ekfUVX98MdXalIQrp0YS1aBA==","shasum":"28c22b66098d5aa91749b02281a5e2111ee83eca","tarball":"https://registry.npmjs.org/@daveremy/imessage-mcp/-/imessage-mcp-0.1.0.tgz","fileCount":68,"unpackedSize":158471,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICArEQ/WHgaIiWtEIC13P1WInh9J/8+hKn/EPTRXYugXAiEAjxqIUgUjn/qZi7wVnw4wc6JGG92eDtPe428AWrv6EvU="}]},"_npmUser":{"name":"daveremy","email":"email@daveremy.com"},"directories":{},"maintainers":[{"name":"daveremy","email":"email@daveremy.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/imessage-mcp_0.1.0_1773667419342_0.15771742098509756"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-16T13:23:39.227Z","0.1.0":"2026-03-16T13:23:39.486Z","modified":"2026-03-16T13:23:39.689Z"},"maintainers":[{"name":"daveremy","email":"email@daveremy.com"}],"description":"MCP server for reading and sending iMessages from Claude Code","homepage":"https://github.com/daveremy/imessage-mcp#readme","keywords":["imessage","mcp","claude","messages","macos"],"repository":{"type":"git","url":"git+https://github.com/daveremy/imessage-mcp.git"},"bugs":{"url":"https://github.com/daveremy/imessage-mcp/issues"},"license":"MIT","readme":"# imessage-mcp\n\nAn [MCP server](https://modelcontextprotocol.io/) that gives AI assistants like [Claude Code](https://docs.anthropic.com/en/docs/claude-code) the ability to read and send iMessages on macOS.\n\nPhone numbers and email addresses are automatically resolved to real names from your Apple Contacts — so you interact with people, not handles.\n\n## What it looks like\n\n```\n> imessage-mcp chats 3\n\n1. Sarah, Mike, Pete, Joel\n   Chat ID: 91 | iMessage, 4 participants | 46 messages | Mar 15, 9:33 PM\n2. Family Group Chat\n   Chat ID: 40 | iMessage, 8 participants | 125 messages | Mar 15, 6:08 PM\n3. Alex Johnson (+15551234567)\n   Chat ID: 67 | iMessage | 12 messages | Mar 15, 4:39 PM\n```\n\n```\n> imessage-mcp messages 67 3\n\n[Mar 15, 2:01 PM] Alex Johnson (+15551234567): Are we still on for Friday?\n[Mar 15, 2:05 PM] Me: Yes! Looking forward to it.\n[Mar 15, 4:39 PM] Alex Johnson (+15551234567): Great, see you then!\n```\n\n## Prerequisites\n\n**macOS only.** This reads the local Messages database directly.\n\n1. **Full Disk Access** — your terminal app needs permission to read `~/Library/Messages/chat.db`\n   - System Settings → Privacy & Security → Full Disk Access → add your terminal (Terminal.app, iTerm2, Ghostty, etc.)\n   - Restart the terminal after granting access\n2. **Contacts permission** (optional but recommended) — for resolving phone numbers to names\n   - If names aren't showing up, grant Contacts access to your terminal app in System Settings\n3. **Messages.app signed in** — required only for sending messages\n4. **Node.js >= 22** — uses the built-in `node:sqlite` module (no native compilation needed)\n\nRun `imessage-mcp status` to verify everything is working.\n\n## Installation\n\n### As a Claude Code MCP server\n\nAdd to your project's `.mcp.json` or `~/.claude/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"imessage-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@daveremy/imessage-mcp\"]\n    }\n  }\n}\n```\n\nThen restart Claude Code. The `im_*` tools will appear automatically.\n\n### As a CLI tool\n\n```bash\nnpx @daveremy/imessage-mcp status       # verify access\nnpx @daveremy/imessage-mcp chats        # list recent conversations\nnpx @daveremy/imessage-mcp messages 42  # read messages from chat 42\n```\n\n## Tools\n\n### im_status\n\nCheck that database access and contact resolution are working.\n\n```\nMessages database: OK\n  Chats: 102\n  Messages: 1432\n\nContacts: OK (77 contacts)\n```\n\n### im_chats\n\nList recent conversations, ordered by last activity. Groups show the group name or resolved participant names. 1:1 chats show the contact name with handle.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `limit` | number | 20 | Maximum chats to return |\n\n### im_messages\n\nRead messages from a specific chat in chronological order. Includes reactions, attachments, edited/unsent indicators, and pagination.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `chatId` | number | required | Chat ID from `im_chats` |\n| `limit` | number | 50 | Messages per page |\n| `cursor` | string | — | Opaque cursor from previous response for loading older messages |\n\nMessages are formatted as:\n```\n[Mar 15, 2:01 PM] Contact Name (+15551234567): message text\n[Mar 15, 2:05 PM] Me: response text\n[Mar 15, 2:06 PM] Me: [Liked \"message text\"]\n[Mar 15, 2:07 PM] Contact Name (+15551234567): photo.jpg [Attachment: photo.jpg, 2.1 MB]\n```\n\n### im_search\n\nSearch message text across all chats or within a specific chat. Scans up to 5,000 recent messages with case-insensitive substring matching.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `query` | string | required | Text to search for |\n| `chatId` | number | — | Limit search to one chat |\n| `limit` | number | 20 | Maximum results |\n\nResults include a completeness line: `(searched 1432 of 1432 total messages)` so you know the coverage.\n\n### im_send\n\nSend a message to an existing chat. The MCP tool description includes a warning to always confirm with the user before sending.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `chatId` | number | required | Chat ID from `im_chats` |\n| `text` | string | required | Message text |\n\nUses JXA (JavaScript for Automation) to send via Messages.app. Only targets existing chat threads by GUID — never creates new conversations.\n\n### im_participants\n\nList everyone in a chat with resolved contact names and service type (iMessage, SMS, RCS).\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `chatId` | number | required | Chat ID from `im_chats` |\n\n## How it works\n\n```\n┌─────────────┐     stdio/JSON-RPC      ┌──────────────┐\n│ Claude Code  │ ◄──────────────────────► │ imessage-mcp │\n└─────────────┘                          └──────┬───────┘\n                                                │\n                         ┌──────────────────────┼──────────────────────┐\n                         │                      │                      │\n                         ▼                      ▼                      ▼\n              ~/Library/Messages/     AddressBook/*.abcddb      osascript (JXA)\n                  chat.db                (read-only)           Messages.app\n                (read-only)           Contact resolution         (send)\n              Message history\n```\n\n- **Reading**: Queries `chat.db` directly via SQLite (read-only). Message text is extracted from the `attributedBody` column using a custom binary parser for Apple's typedstream format (NSArchiver), falling back to the `text` column.\n- **Contacts**: Reads Apple's AddressBook SQLite databases to build a phone/email → name lookup map. Phone numbers are normalized for matching (strips formatting, handles US country code).\n- **Sending**: Invokes Messages.app through JXA (`osascript -l JavaScript`). Message text is safely encoded via `JSON.stringify()`. Only targets existing conversations by chat GUID.\n\n## CLI reference\n\n```\nimessage-mcp                                      Start MCP server (stdio)\nimessage-mcp status                               Check database access\nimessage-mcp chats [limit]                        List recent chats\nimessage-mcp messages <chatId> [limit] [cursor]   Read messages\nimessage-mcp search <query> [chatId] [limit]      Search messages\nimessage-mcp participants <chatId>                 List participants\nimessage-mcp send <chatId> <text>                  Send a message\n```\n\n## Development\n\n```bash\ngit clone https://github.com/daveremy/imessage-mcp.git\ncd imessage-mcp\nnpm install\nnpm run build\n\n# Test directly\nnpx tsx src/cli.ts status\nnpx tsx src/cli.ts chats\n\n# Test as MCP server\nnpx @modelcontextprotocol/inspector -- npx tsx src/mcp.ts\n```\n\n### Project structure\n\n```\nsrc/\n  mcp.ts              MCP server entry (stdio transport, tool registration)\n  cli.ts              CLI entry (argument parsing, dual-mode)\n  db.ts               SQLite queries against ~/Library/Messages/chat.db\n  contacts.ts         Contact resolution from AddressBook databases\n  typedstream.ts      Binary parser for attributedBody (NSArchiver format)\n  applescript.ts      Send messages via JXA → Messages.app\n  types.ts            TypeScript interfaces\n  version.ts          Version from package.json\n  tools/\n    status.ts         im_status implementation\n    chats.ts          im_chats implementation\n    messages.ts       im_messages implementation\n    search.ts         im_search implementation\n    send.ts           im_send implementation\n    participants.ts   im_participants implementation\n```\n\n## Known limitations\n\n- **Phone normalization is US-centric**: 10-digit numbers get a \"1\" prefix. International numbers with different country code lengths may not resolve to contacts.\n- **Typedstream parser is best-effort**: Handles the common single-string NSAttributedString. Multi-segment bodies, inline attachment references, or unusual class hierarchies return `(no text content)`.\n- **Attachments are metadata only**: Filenames and sizes are shown, but attachment file contents are not read or returned.\n- **Search scans recent messages**: Up to 5,000 most recent messages, not the full history. The completeness line tells you exactly how much was covered.\n- **No conversation creation**: `im_send` only sends to existing chats. It cannot start new conversations.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-73af2b1ba520b6e6429d990aee7de46a"}