Mac Messages
An MCP server that securely interfaces with your iMessage database via the Model Context Protocol (MCP), allowing LLMs to query and analyze iMessage conversations. It includes robust phone number validation, attachment processing, contact management,
What is Mac Messages?
Mac Messages is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to mcp server that securely interfaces with your imessage database via the model context protocol (mcp), allowing llms to query and analyze imessage conversations. it includes robust phone number validat...
An MCP server that securely interfaces with your iMessage database via the Model Context Protocol (MCP), allowing LLMs to query and analyze iMessage conversations. It includes robust phone number validation, attachment processing, contact management,
This server falls under the Communication category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- An MCP server that securely interfaces with your iMessage da
Use Cases
Maintainer
Works with
Installation
NPM
npx -y mac-messages-mcpManual Installation
npx -y mac-messages-mcpConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Mac Messages
Mac Messages MCP is a Python server that provides secure, read-write access to your macOS iMessage database via the Model Context Protocol, enabling LLMs to query conversations, search messages, send iMessages or SMS, manage contacts, and process attachments. It features robust phone number validation in E.164 format, automatic iMessage/SMS fallback, group chat access by chat ID, and progressive attachment discovery for photos and PDFs. Because it reads the SQLite chat database directly, it requires Full Disk Access permission on macOS.
Prerequisites
- macOS 11 (Big Sur) or newer
- Python 3.10 or newer
- uv package manager (install via `brew install uv` or the official installer)
- Full Disk Access granted to your terminal app or Claude Desktop in System Settings > Privacy & Security > Full Disk Access
- An MCP client such as Claude Desktop or Cursor
Install uv
Install the uv package manager, which is required to run mac-messages-mcp.
brew install uvGrant Full Disk Access
Open System Settings > Privacy & Security > Full Disk Access and add your terminal application (e.g., iTerm2, Terminal) or Claude Desktop to the allowlist. This is required to read the iMessage SQLite database at ~/Library/Messages/chat.db.
Install the package
Install mac-messages-mcp from PyPI using pip via uv.
uv pip install mac-messages-mcpConfigure Claude Desktop
Add the MCP server to your Claude Desktop configuration file using uvx for isolated execution.
{
"mcpServers": {
"messages": {
"command": "uvx",
"args": ["mac-messages-mcp"]
}
}
}Restart Claude Desktop
Restart Claude Desktop to load the new MCP server. The server will connect to your iMessage database on startup.
Test the connection
Ask Claude to retrieve recent messages to verify access. Use E.164 phone number format (+14155551234) when specifying contacts.
Mac Messages Examples
Client configuration
Claude Desktop configuration for mac-messages-mcp using uvx. No API keys are required — access is controlled by macOS Full Disk Access permissions.
{
"mcpServers": {
"messages": {
"command": "uvx",
"args": ["mac-messages-mcp"]
}
}
}Prompts to try
Use these prompts in Claude Desktop once the mac-messages-mcp server is connected and Full Disk Access is granted.
- "Show me my most recent 20 messages."
- "Find all messages from +14155551234 in the last 7 days."
- "What did John say in our group chat this week? (use chat ID from recent conversations)"
- "Send a message to +14155551234 saying I'll be 10 minutes late."
- "Search my messages for any mentions of the word 'invoice'."
- "List all photo attachments received in the last 30 days."Troubleshooting Mac Messages
Server fails to start or returns 'permission denied' accessing chat.db
Ensure Full Disk Access is granted in System Settings > Privacy & Security > Full Disk Access for the app running the server (Claude Desktop or your terminal). After granting access, fully quit and relaunch the app — a simple restart is not enough.
Messages send as SMS instead of iMessage unexpectedly
This is by design — the server automatically falls back to SMS when the recipient is not on iMessage. To check iMessage availability for a contact before sending, ask Claude to check the recipient's platform first using the iMessage detection tool.
uvx: command not found when Claude Desktop launches the server
Install uv via Homebrew (`brew install uv`) or the official installer and ensure it is on the system PATH. Claude Desktop may not inherit your shell PATH; you can specify the full path to uvx in the 'command' field of the config (run `which uvx` to find it).
Frequently Asked Questions about Mac Messages
What is Mac Messages?
Mac Messages is a Model Context Protocol (MCP) server that mcp server that securely interfaces with your imessage database via the model context protocol (mcp), allowing llms to query and analyze imessage conversations. it includes robust phone number validation, attachment processing, contact management, It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Mac Messages?
Install via npm with the command: npx -y mac-messages-mcp. Then add the server configuration to your AI client's JSON config file (e.g., claude_desktop_config.json or .cursor/mcp.json).
Which AI clients work with Mac Messages?
Mac Messages works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Mac Messages free to use?
Yes, Mac Messages is open source and available under the MIT License license. You can use it freely in both personal and commercial projects.
Mac Messages Alternatives — Similar Communication Servers
Looking for alternatives to Mac Messages? Here are other popular communication servers you can use with Claude, Cursor, and VS Code.
Slack
★ 86.1kEnables interaction with Slack workspaces through comprehensive channel management, messaging, user management, file uploads, and Block Kit formatting. Features secure credential storage via macOS Keychain and supports all major Slack operations incl
LibreChat
★ 37.3kEnhanced ChatGPT Clone: Features Agents, MCP, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenA
Note Gen
★ 11.9kA cross-platform Markdown AI note-taking software.
DeepChat
★ 5.8k🐬DeepChat - A smart assistant that connects powerful AI to your personal world
WhatsApp MCP
★ 5.7kConnects AI assistants to the official Meta WhatsApp Cloud API for managing conversations and sending various message types through natural language. It provides tools for media management, template messages, and real-time webhook processing without
Apple
★ 3.1kEnables interaction with Apple apps like Messages, Notes, and Contacts through the MCP protocol to send messages, search, and open app content using natural language.
Browse More Communication MCP Servers
Explore all communication servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Mac Messages in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Mac Messages?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.