Enables sending and reading iMessages, retrieving message history, searching across conversations, and managing contacts with fuzzy matching and macOS Contacts sync.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@iMessage MCP Serversend a message to John saying I'll be there in 10 minutes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
iMessage Gateway CLI
The fastest iMessage integration for Claude Code. Direct CLI architecture delivers 19x faster performance than MCP-based alternatives.
Features
Send Messages: Send iMessages using natural language
Read Messages: Retrieve message history with contacts or phone numbers
Smart Contact Lookup: Fuzzy matching for contact names
Semantic Search (RAG): AI-powered search across iMessages, SuperWhisper, Notes
Follow-up Detection: Find conversations needing response
Group Chats: List and read group conversations
Analytics: Conversation patterns and statistics
Performance
Operation | Gateway CLI | MCP-based | Speedup |
List contacts | 40ms | ~763ms | 19x |
Find messages | 43ms | ~763ms | 18x |
Unread messages | 44ms | ~763ms | 17x |
Groups | 61ms | ~763ms | 12x |
Semantic search | 150ms | ~900ms | 6x |
Requirements
macOS (required - iMessage is macOS only)
Python 3.9+
Full Disk Access permission (for reading message history)
Quick Start
1. Clone and Install
2. Set Up Contacts
3. Grant Permissions
Full Disk Access (for reading messages):
System Settings → Privacy & Security → Full Disk Access
Add Terminal.app or your Python interpreter
Automation (for sending messages):
Will be requested automatically on first send
4. Test It Out
Command Reference (27 Commands)
Messaging (3)
Reading (12)
Groups (2)
Analytics (3)
Contacts (1)
Semantic Search / RAG (6)
Architecture
Why Gateway CLI?
The Gateway CLI architecture bypasses MCP framework overhead entirely:
Direct execution: Python script runs immediately, no JSON-RPC initialization
No session startup: MCP servers have ~700-800ms cold start per session
Smaller footprint: No MCP SDK dependency, simpler codebase
Same reliability: Uses identical
MessagesInterfacecode for all operations
Claude Code Integration
Using the Skill
The imessage-gateway skill provides natural language access:
Bash Pre-approval
Ensure your settings include:
Configuration
Contact Format
Contacts are stored in config/contacts.json:
Phone numbers can be in any format - they're normalized automatically.
Troubleshooting
"Contact not found"
Run
python3 scripts/sync_contacts.pyto sync contactsCheck
config/contacts.jsonexists and has contactsTry partial names (e.g., "John" instead of "John Doe")
"Permission denied" reading messages
Grant Full Disk Access to Terminal/Python
Restart Terminal after granting permission
Verify:
ls ~/Library/Messages/chat.db
Messages show "[message content not available]"
Some older messages use a different format
Attachment-only messages don't have text content
This is normal for some message types
Development
Privacy & Security
All data stays local on your Mac
No cloud services for core functionality
Contacts file is gitignored by default
Message history accessed read-only
Optional OpenAI API for semantic search embeddings
MCP Server (Archived)
The MCP server has been archived in mcp_server_archive/. See mcp_server_archive/ARCHIVED.md for restoration instructions if needed.
License
MIT License - see LICENSE for details.
Built for use with