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?

This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.

iMessage MCP Server

by wolfiesch

Overview Schema Source Related Servers Discussions Admin

Python

Local

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

Related MCP server: imessage-mcp

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Related MCP Connectors

autoMessage
app.automessage
Send and read iMessages from your own Mac and Apple ID — drafts, history and contacts.
Communication App Automation
1
https://automessage-mcp-tfsfyvwypq-uc.a.run.app
Local MCP B
com.local-mcp
Mac & Windows: let ChatGPT, Claude & Cursor use your email, calendar, iMessage, Teams, files.
Calendar Management Email File Systems
3033
https://local-mcp.com/mcp
WaBot
com.astranexo.wabot
Your own WhatsApp in Claude and ChatGPT: read chats, draft replies, send messages you approve.
Communication App Automation
1
https://wabot.astranexo.com/mcp
Uxen
com.rrrfirstchat
Your Telegram, WhatsApp, Instagram, mail and calendar in Claude or ChatGPT. Never sends messages.
Communication Email Calendar Management
1
https://api.rrrfirstchat.com/mcp

Related MCP Servers

texting
Communication Search
bowlofarugula
A
license
Not graded
quality
D
maintenance
Enables Claude to send and read iMessages on macOS, with human approval required for sending and no auto-replies.
Updated 5 months ago (2026-06-13 01:01 UTC)
7 npm
2
Apache 2.0
imessage-mcp
Communication File Systems
kamrenkennedy
A
license
A
quality
D
maintenance
Connects Claude Desktop to iMessage on macOS, enabling reading conversations, searching messages, sending texts, and managing attachments.
Updated 6 months ago (2026-05-08 18:21 UTC)
7
7 npm
MIT
claude-imessage-mcp
Communication App Automation
P-bit-display
A
license
Not graded
quality
D
maintenance
Enables Claude to send and receive iMessage/SMS messages through macOS, with support for attachments, chat history, and real-time message monitoring.
Updated 9 months ago (2026-02-06 15:52 UTC)
MIT
Apple Messages MCP
Communication App Automation
falconbradley
A
license
A
quality
A
maintenance
Enables Claude on macOS to read, search, and send iMessage, SMS, and RCS messages, with tools for stats, chat history, attachments, and message composition.
Updated a month ago (2026-10-06 19:35 UTC)
9
MIT

Appeared in Searches

A server for finding information about iMessage