# Mac Messages MCP (MCP server)

> Mac Messages MCP is an MCP server that adds messaging tools to AI assistants such as Claude Desktop, Claude Code and Cursor. An MCP server that securely interfaces with your iMessage database via the Model Context Protocol (MCP), allowing LLMs to… It has 331 GitHub stars, is released under the MIT license and runs locally with uvx mac-messages-mcp.

Use Claude, Codex, Cursor, VS Code, or any local MCP client to search, read, and send messages through the macOS Messages app.

## Key facts

| Fact | Value |
|---|---|
| Repository | https://github.com/carterlasalle/mac_messages_mcp |
| GitHub stars | 331 |
| License | MIT |
| Language | Python |
| Transport | stdio |
| Packages | pypi: mac-messages-mcp |
| Remote URL | none |
| Needs API key | no |
| Official | no |
| Works with | Claude Desktop, Claude Code, Cursor, VS Code |
| Category | Communication |
| Latest release | v1.1.0 (Sep 1, 2026) |
| Last commit | Oct 6, 2026 |

## Install

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "mac-messages-mcp": {
      "command": "uvx",
      "args": [
        "mac-messages-mcp"
      ],
      "env": {
        "MAC_MESSAGES_REGION": "your-value"
      }
    }
  }
}
```

Settings > Developer > Edit Config. macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\. Restart Claude Desktop afterwards.

### Claude Code

```sh
claude mcp add --env MAC_MESSAGES_REGION=your-value --transport stdio mac-messages-mcp -- uvx mac-messages-mcp
```

### Cursor (.cursor/mcp.json)

```json
{
  "mcpServers": {
    "mac-messages-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mac-messages-mcp"
      ],
      "env": {
        "MAC_MESSAGES_REGION": "your-value"
      }
    }
  }
}
```

Project file; use ~/.cursor/mcp.json to enable it in every project.

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "mac-messages-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mac-messages-mcp"
      ],
      "env": {
        "MAC_MESSAGES_REGION": "your-value"
      }
    }
  }
}
```

Config formats checked against the official docs on 2026-10-07.

## Environment variables

- `MAC_MESSAGES_REGION`: Shown in the README's example configuration.

## Tools

- `tool_get_recent_messages`: Read recent messages, filtered by contact, group chat ID, date range, or unread state; page with limit/offset
- `tool_fuzzy_search_messages`: Search message bodies by approximate text match, scoped to a contact or chat; defaults to 30 days, or hours=0
- `tool_list_conversations`: List every conversation with kind, message count, unread count, and last activity
- `tool_wait_for_new_messages`: Block until a message newer than a ROWID cursor arrives, or the timeout expires
- `tool_find_contact`: Fuzzy-match a name in Contacts and return phone numbers
- `tool_get_chats`: List named group chats and their identifiers
- `tool_search_attachments`: Find attachment metadata by date, contact, MIME type, and limit
- `tool_search_attachment_contents`: Search inside attachment text/PDF contents by date, contact, and MIME type
- `tool_get_attachment`: Fetch one attachment by ID, inline when supported or as a local path
- `tool_check_imessage_availability`: Check likely iMessage availability for a phone number or email
- `tool_check_db_access`: Diagnose access to ~/Library/Messages/chat.db
- `tool_check_contacts`: Return a contact count and a small sample
- `tool_check_addressbook`: Diagnose Contacts/AddressBook database access
- `tool_send_message`: Send one direct or group message through Messages.app, optionally with file attachments and elicitation approval
- `tool_create_contact`: Create one Contacts.app entry with a phone number
- `tool_schedule_message`: Queue a message for later delivery while this server process runs
- `tool_list_scheduled_messages`: List the in-process scheduled-message queue and its status
- `tool_cancel_scheduled_message`: Cancel one pending scheduled message

## Similar MCP servers

- [Strata](https://appsgit.com/mcp-servers/strata): MCP server for progressive tool usage at any scale (see https://klavis.ai). (5,807 stars, Apache-2.0, official)
- [Vexa](https://appsgit.com/mcp-servers/vexa): Meeting bot and transcripts for Google Meet, Teams and Zoom. (2,856 stars, Apache-2.0, official, needs API key)
- [MCP Server for WinDbg Crash Analysis](https://appsgit.com/mcp-servers/mcp-server-for-windbg-crash-analysis): A Model Context Protocol server for Windows crash dump analysis using WinDbg/CDB. (1,607 stars, MIT)
- [Rocketmq Rust](https://appsgit.com/mcp-servers/rocketmq-rust): 🚀 Apache RocketMQ built in Rust 🦀 — faster, safer, and more memory-efficient. (1,524 stars, Apache-2.0)
- [Wassette](https://appsgit.com/mcp-servers/wassette): Wassette: A security-oriented runtime that runs WebAssembly Components via MCP. (957 stars, MIT, official)
- [Line Bot MCP Server](https://appsgit.com/mcp-servers/line-bot-mcp-server): MCP server that integrates the LINE Messaging API to connect an AI Agent to the LINE Official Account. (783 stars, Apache-2.0, official, needs API key)

---

Canonical page: https://appsgit.com/mcp-servers/mac-messages-mcp
Source: appsgit (https://appsgit.com), the app store for github. Data from the GitHub API, refreshed nightly.
Machine access: JSON API https://appsgit.com/api/v1/apps (OpenAPI: https://appsgit.com/openapi.json), MCP server https://mcp.appsgit.com/mcp, full index https://appsgit.com/llms-full.txt.