Which integrations are available for this server?

Enables sending and reading iMessages, retrieving message history, searching across conversations, and managing contacts with fuzzy matching and macOS Contacts sync.

How do I use iMessage MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@iMessage MCP Server send 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

macOS Python License Claude Code

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

git clone https://github.com/yourusername/imessage-gateway.git
cd imessage-gateway
pip install -r requirements.txt

2. Set Up Contacts

# Sync from macOS Contacts (recommended)
python3 scripts/sync_contacts.py

# Or manual setup
cp config/contacts.example.json config/contacts.json
# Edit config/contacts.json with your 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

# List your contacts
python3 gateway/imessage_client.py contacts --json

# Check unread messages
python3 gateway/imessage_client.py unread --json

# Get recent messages
python3 gateway/imessage_client.py recent --limit 20 --json

# Send a message
python3 gateway/imessage_client.py send "John" "Hey, are you free for coffee?"

Command Reference (27 Commands)

Messaging (3)

# Send to contact
python3 gateway/imessage_client.py send "John" "Hello!"

# Send to phone number directly
python3 gateway/imessage_client.py send-by-phone "+14155551234" "Hi there!"

# Add a new contact
python3 gateway/imessage_client.py add-contact "Jane Doe" "+14155559876"

Reading (12)

# Messages with a contact
python3 gateway/imessage_client.py messages "John" --limit 20 --json

# Find messages (keyword search)
python3 gateway/imessage_client.py find "John" --query "meeting" --json

# Recent across all contacts
python3 gateway/imessage_client.py recent --limit 50 --json

# Unread messages
python3 gateway/imessage_client.py unread --json

# Recent phone handles
python3 gateway/imessage_client.py handles --days 30 --json

# Messages from unknown senders
python3 gateway/imessage_client.py unknown --days 7 --json

# Attachments
python3 gateway/imessage_client.py attachments "John" --json

# Voice messages
python3 gateway/imessage_client.py voice --json

# Links shared
python3 gateway/imessage_client.py links --days 30 --json

# Message thread
python3 gateway/imessage_client.py thread "<message-guid>" --json

# Scheduled messages
python3 gateway/imessage_client.py scheduled --json

# Conversation summary
python3 gateway/imessage_client.py summary "John" --days 7 --json

Groups (2)

# List group chats
python3 gateway/imessage_client.py groups --json

# Messages from a group
python3 gateway/imessage_client.py group-messages --group-id "chat123456" --json

Analytics (3)

# Conversation analytics
python3 gateway/imessage_client.py analytics "John" --days 30 --json

# Follow-ups needed
python3 gateway/imessage_client.py followup --days 7 --json

# Reactions
python3 gateway/imessage_client.py reactions "John" --json

Contacts (1)

# List all contacts
python3 gateway/imessage_client.py contacts --json

Semantic Search / RAG (6)

# Index iMessages for semantic search
python3 gateway/imessage_client.py index --source=imessage --days 30

# Index SuperWhisper transcriptions
python3 gateway/imessage_client.py index --source=superwhisper

# Index Notes
python3 gateway/imessage_client.py index --source=notes

# Index all local sources
python3 gateway/imessage_client.py index --source=local

# Semantic search
python3 gateway/imessage_client.py search "dinner plans with Sarah" --json

# AI-formatted context
python3 gateway/imessage_client.py ask "What restaurant did Sarah recommend?"

# Knowledge base stats
python3 gateway/imessage_client.py stats --json

# List available/indexed sources
python3 gateway/imessage_client.py sources --json

# Clear indexed data
python3 gateway/imessage_client.py clear --source=imessage --force

Architecture

Messages.db (SQLite) ←─ ~/Library/Messages/chat.db
        ↓
MessagesInterface ────→ SQLite queries (read)
        │                AppleScript → Messages.app (send)
        ↓
ContactsManager ──────→ config/contacts.json (fuzzy matching)
        ↓
Gateway CLI ──────────→ gateway/imessage_client.py
        ↓
Claude Code ──────────→ Bash tool calls

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 MessagesInterface code for all operations

Claude Code Integration

Using the Skill

The imessage-gateway skill provides natural language access:

/imessage-gateway unread
/imessage-gateway send John "Running late!"
/imessage-gateway search "meeting next week"

Bash Pre-approval

Ensure your settings include:

Bash(python3:*::*)

Configuration

Contact Format

Contacts are stored in config/contacts.json:

{
  "contacts": [
    {
      "name": "John Doe",
      "phone": "14155551234",
      "relationship_type": "friend",
      "notes": "Optional notes"
    }
  ]
}

Phone numbers can be in any format - they're normalized automatically.

Troubleshooting

"Contact not found"

Run python3 scripts/sync_contacts.py to sync contacts
Check config/contacts.json exists and has contacts
Try 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

# Run tests
pytest tests/ -v

# Run performance benchmarks
python3 -m Texting.benchmarks.run_benchmarks

# Sync contacts
python3 scripts/sync_contacts.py

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 Claude Code

iMessage MCP Server