jons-mcp-imessage

A local MCP server for querying and sending iMessages on macOS.

This FastMCP server exposes tools through the Model Context Protocol (MCP), enabling AI assistants to read your iMessage history and send messages.

Requirements

• macOS (tested on Tahoe 26.x, should work on recent versions)

• Python 3.10+

• Messages.app (for sending messages)

Permissions Required

This server requires specific macOS permissions to function. Permission issues are the most common cause of problems.

Full Disk Access (Required for Reading Messages)

The application running this server needs Full Disk Access to read ~/Library/Messages/chat.db.

To grant Full Disk Access:

1. Open System Settings (or System Preferences on older macOS)

2. Navigate to Privacy & Security → Full Disk Access

3. Click the lock icon and authenticate if needed

4. Click the + button

5. Add the appropriate application:

   • If using Claude Desktop: Add Claude.app (usually in /Applications)

   • If running from terminal: Add your terminal app (e.g., Terminal.app, iTerm.app, Zed.app)

   • If running via another app: Add that specific application

6. Restart the application after granting access

How to verify: Run check_permissions tool - it will report whether database access is working.

Automation Permission (Required for Sending Messages)

To send messages via AppleScript, the application needs permission to control Messages.app.

This permission is prompted automatically the first time you try to send a message. Click "OK" to allow.

To manually grant or verify:

1. Open System Settings → Privacy & Security → Automation

2. Find your application (Terminal, Claude Desktop, etc.)

3. Ensure Messages is checked

Contacts Permission (Optional - For Contact Name Enrichment)

The server can enrich message responses with contact names from your Contacts app. This is optional - all features work without it, but you'll see phone numbers/emails instead of names.

To enable contact name enrichment:

1. Open System Settings (or System Preferences on older macOS)

2. Navigate to Privacy & Security → Contacts

3. Click the lock icon and authenticate if needed

4. Click the + button

5. Add the appropriate application:

   • If using Claude Desktop: Add Claude.app (usually in /Applications)

   • If running from terminal: Add your terminal app (e.g., Terminal.app, iTerm.app)

6. Restart the application after granting access

What you get with Contacts permission:

• Message responses include contact_name field (e.g., "John Smith" instead of just "+15551234567")

• Conversation responses include participant_names field

• lookup_contact tool becomes available for explicit contact lookups

Without Contacts permission:

• Contact name fields will be null

• lookup_contact returns an error message

• All other functionality works normally (graceful degradation)

Installation

Running the Server

Adding to Claude Code

Adding to Claude Desktop

Add the following to your Claude Desktop configuration file:

Location: ~/Library/Application Support/Claude/claude_desktop_config.json

Notes:

• Replace /path/to/jons-mcp-imessage with the actual path to this repository

• Replace sk-your-openai-api-key with your OpenAI API key (required for semantic search)

• If you don't have an OpenAI key, omit the env section entirely - keyword search will still work

• Restart Claude Desktop after modifying the config

Search Features

The search system combines two powerful search methods:

Keyword Search (FTS5)

Full-text search using SQLite FTS5 with BM25 ranking. Supports:

• Phrase search: "exact phrase"

• Prefix matching: word*

• Proximity: word1 NEAR word2

• Boolean: word1 AND word2, word1 OR word2, NOT word

Semantic Search

AI-powered search using OpenAI embeddings to find conceptually similar messages, even when exact keywords don't match.

Setup

1. Basic Setup (keyword search only): Works out of the box

2. Full Setup (hybrid search): Set your OpenAI API key:

   export OPENAI_API_KEY=your-api-key

Search Modes

• hybrid (default): Combines keyword + semantic results using RRF

• keyword: FTS5 only (no API key needed)

• semantic: Embedding similarity only (requires API key)

Index Management

The search index is stored separately from iMessage's chat.db at: ~/.local/share/jons-mcp-imessage/search_index.db

Tools available:

• search_index_status - Check index health and sync status

• rebuild_search_index - Full reindex (use if issues occur)

Troubleshooting

Available Tools

Reading Messages

Sending Messages

send_message Limitations

Important: The send_message tool has significant limitations:

1. Existing conversations only: Can only send to contacts you have previously messaged. New contacts require starting a conversation manually in Messages.app first.

2. No delivery confirmation: The tool reports success when the message is handed to Messages.app, but cannot confirm actual delivery. Messages may silently fail if:

   • The recipient has blocked you

   • The phone number/email is invalid

   • Network issues occur

3. Messages.app must be running: If Messages.app is not running, the tool will fail with a "Messages not running" error.

4. Service detection: By default, attempts iMessage first. Use service="SMS" to force SMS for non-iMessage contacts.

Example Usage

Troubleshooting

"Permission denied" or "Unable to read database"

Cause: Full Disk Access not granted.

Fix: Follow the Full Disk Access instructions above. Make sure to:

• Grant access to the correct application (the one actually running the server)

• Restart the application after granting access

"Messages not running (-600)"

Cause: Messages.app is not running.

Fix: Open Messages.app before sending messages.

"Not allowed to send Apple events (-1743)"

Cause: Automation permission not granted.

Fix:

1. Go to System Settings → Privacy & Security → Automation

2. Find your application and enable Messages access

3. If not listed, try sending a message again to trigger the permission prompt

"Can't get buddy id" or "existing conversations only"

Cause: Trying to message a contact you haven't messaged before.

Fix: Start a conversation with this contact manually in Messages.app first, then try again.

Messages appear empty or "(non-text message)"

Cause: The message contains only attachments (images, videos) or is a system message (like "renamed the group").

Note: This is expected behavior. The server extracts text content only.

Privacy Considerations

This server accesses your local iMessage database and optionally your Contacts database. Be aware that:

• All message history is accessible: The server can read all messages stored locally

• Contact information is exposed: Phone numbers and email addresses are visible

• Attachments are referenced: File paths to attachments (photos, videos) are included

• No cloud access: Only locally-stored messages are accessible (not messages only on iCloud)

Contact Name Privacy

If you grant Contacts permission:

• Contact names come from YOUR Contacts app: The server reads your personal contact list to enrich message responses

• Names are NOT stored: Contact names are resolved at query time and are NOT stored in any database or search index

• Names are cached in-memory only: The server loads all contacts into memory on first use, cache is cleared on restart

• All Contacts databases are read: Includes main Contacts DB plus any per-source databases (iCloud, CardDAV, etc.)

Use appropriate caution when granting AI assistants access to this server.

Development

Setup

Running Tests

Code Quality

Project Structure

License

MIT