Skip to main content
Glama
wolfiesch

iMessage MCP Server

by wolfiesch
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/wolfiesch/imessage-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server