iMessage MCP Server

A personalized iMessage MCP (Model Context Protocol) server that lets Claude send and read iMessages on macOS.

Features

• Send Messages: Send iMessages using natural language ("Text John saying I'm running late")
• Read Messages: Retrieve recent message history with any contact
• Smart Contact Lookup: Find contacts by name with fuzzy matching
• Cross-Conversation Search: Search messages across all contacts
• macOS Contacts Sync: Auto-sync contacts from your macOS Contacts app

Requirements

• macOS (required - iMessage is macOS only)
• Python 3.9+
• Claude Code or Claude Desktop (MCP client)
• Full Disk Access permission (for reading message history)

Quick Start

1. Clone and Install

git clone https://github.com/yourusername/imessage-mcp.git
cd imessage-mcp

# Install dependencies
pip install -r requirements.txt

2. Set Up Contacts

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

# Option B: Manual setup
cp config/contacts.example.json config/contacts.json
# Edit config/contacts.json with your contacts

3. Grant Permissions

1. Full Disk Access (for reading messages):

   • System Settings → Privacy & Security → Full Disk Access
   • Add Terminal.app or your Python interpreter

2. Automation (for sending messages):

   • Will be requested automatically on first send

4. Register with Claude Code

# Using Claude Code CLI
claude mcp add -t stdio imessage-mcp -- python3 /path/to/imessage-mcp/mcp_server/server.py

# Then restart Claude Code

5. Test It Out

In Claude Code, try:

List my contacts

Show my recent messages with John

Send a message to Jane saying "Hey, are you free for coffee tomorrow?"

Available MCP Tools

Tool	Description
list_contacts	List all configured contacts
send_message	Send an iMessage to a contact by name
get_recent_messages	Get recent messages with a specific contact
get_all_recent_conversations	Get recent messages across all contacts
search_messages	Full-text search across all messages
get_messages_by_phone	Get messages by phone number directly

Project Structure

imessage-mcp/
├── mcp_server/
│   └── server.py          # MCP server entry point
├── src/
│   ├── messages_interface.py  # iMessage send/read
│   ├── contacts_manager.py    # Contact lookup
│   └── contacts_sync.py       # macOS Contacts sync
├── config/
│   ├── contacts.json          # Your contacts (gitignored)
│   └── contacts.example.json  # Example template
├── scripts/
│   ├── sync_contacts.py       # Sync from macOS Contacts
│   ├── test_mcp_protocol.py   # Test MCP protocol
│   └── test_mcp_tools.py      # Test tool functionality
└── tests/                     # Unit tests

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.

Server Config

Optional settings in config/mcp_server.json:

{
  "logging": {
    "level": "INFO"
  },
  "contacts_sync": {
    "fuzzy_match_threshold": 0.85
  }
}

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

MCP server not appearing in Claude Code

• Verify registration: claude mcp list
• Check Python path: which python3
• Restart Claude Code after adding the server

How It Works

1. Sending: Uses AppleScript to control Messages.app
2. Reading: Directly queries ~/Library/Messages/chat.db (SQLite)
3. Contacts: Syncs from macOS Contacts via PyObjC framework

Claude Code Skill (Optional)

This repo includes a Claude Code skill at .claude/skills/imessage-texting/ with usage examples for each MCP tool.

To use it, clone this repo - Claude Code will automatically pick up the skill from the .claude/skills/ directory.

Development

# Run tests
pytest tests/ -v

# Test MCP protocol manually
python3 scripts/test_mcp_protocol.py

# Test tools
python3 scripts/test_mcp_tools.py

Privacy & Security

• All data stays local on your Mac
• No cloud services or external APIs
• Contacts file is gitignored by default
• Message history accessed read-only

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! Please open an issue or PR.

---

Built for use with Claude Code and Claude Desktop