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
Manual Installation
npx 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-based MCP server that interfaces with your Mac's local iMessage database, giving AI assistants the ability to read, search, and send iMessages entirely through natural language. It supports fuzzy search across message history, attachment discovery, contact lookups, and automatic iMessage vs SMS selection before sending. The server is designed for macOS power users who want to query conversation history, extract shared files, or automate message-based workflows from within Claude Desktop or Cursor.
Prerequisites
- macOS 11 (Big Sur) or later
- Python 3.10+ and the uv package manager (install with: brew install uv)
- Full Disk Access permission granted to your terminal application or Claude Desktop in System Settings > Privacy & Security > Full Disk Access
- An MCP client such as Claude Desktop or Cursor
- iMessage configured and signed in on the Mac
Install the uv package manager
Mac Messages MCP uses uv to manage its Python dependencies. If you do not have uv installed, install it via Homebrew. This enables the uvx command used in the MCP configuration.
brew install uvGrant Full Disk Access to your terminal and Claude Desktop
Open System Settings > Privacy & Security > Full Disk Access. Enable access for your terminal application (e.g., Terminal, iTerm2) and for Claude Desktop. This is required because the server reads the iMessage SQLite database at ~/Library/Messages/chat.db.
Add the server to your MCP client configuration
Edit your Claude Desktop configuration file to include the mac-messages-mcp server. The server is run via uvx, so no separate install step is needed — uvx will download the package on first run.
{
"mcpServers": {
"messages": {
"command": "uvx",
"args": ["mac-messages-mcp"]
}
}
}Restart Claude Desktop
Quit and relaunch Claude Desktop. The server will start automatically via uvx. On the first launch, uvx will download the mac-messages-mcp package from PyPI, which may take a few seconds.
Verify the connection
In Claude Desktop, ask a simple question such as 'Show me my most recent 5 messages' to confirm the server can read your iMessage database. If it works, you will see actual message data returned.
Mac Messages Examples
Client configuration
Claude Desktop configuration for Mac Messages MCP using uvx to run the server.
{
"mcpServers": {
"messages": {
"command": "uvx",
"args": ["mac-messages-mcp"]
}
}
}Prompts to try
Example prompts for reading, searching, and sending iMessages via the MCP server.
- "Show me all messages I received from +14155551234 in the last 7 days."
- "Search my messages for any conversation mentioning 'project deadline'."
- "List all image attachments shared in my chat with John."
- "Send an iMessage to +14155550100 saying: 'Running 10 minutes late, be there soon.'"
- "Find all messages from the last 48 hours and summarize what people are asking me about."Troubleshooting Mac Messages
Server returns a permission error when accessing the iMessage database
Open System Settings > Privacy & Security > Full Disk Access and ensure both your terminal and Claude Desktop are listed and toggled on. You may need to quit and relaunch the apps after granting access. The database is at ~/Library/Messages/chat.db and requires Full Disk Access.
uvx command not found when Claude Desktop tries to start the server
Install uv via Homebrew with 'brew install uv'. Then confirm uvx is on your PATH by running 'which uvx' in a terminal. If Claude Desktop cannot find it, add the uv bin directory (typically ~/.local/bin) to your shell's PATH and restart Claude Desktop.
Sending a message fails or sends as SMS instead of iMessage
The server checks iMessage availability before sending. Ensure the recipient's number is registered with iMessage. Phone numbers must be in E.164 format (e.g., +14155551234). If iMessage is unavailable, the server will fall back to SMS automatically.
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?
Follow the installation instructions on the Mac Messages GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
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. 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.