License

Skip to content

You signed in with another tab or window. Reload
to refresh your session. You signed out in another tab or window. Reload
to refresh your session. You switched accounts on another tab or window. Reload
to refresh your session. Dismiss alert

carterlasalle / mac_messages_mcp Public

• Notifications
  You must be signed in to change notification settings

• Fork 1

• Star 21

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, group chat handling, and full support for sending and receiving messages.

pypi.org/project/mac-messages-mcp/

License

MIT license

21 stars
1 fork
Branches
Tags
Activity

Star

Notifications
You must be signed in to change notification settings

carterlasalle/mac_messages_mcp

main

Branches
Tags

Go to file

Code

Folders and files

| Name | | Name | Last commit message | Last commit date |
| --- | --- | --- | --- |
| Latest commit
-------------

History
-------

32 Commits

| | |
| .github | | .github | | |
| mac_messages_mcp | | mac_messages_mcp | | |
| scripts | | scripts | | |
| tests | | tests | | |
| .gitignore | | .gitignore | | |
| LICENSE | | LICENSE | | |
| README.md | | README.md | | |
| VERSIONING.md | | VERSIONING.md | | |
| main.py | | main.py | | |
| pyproject.toml | | pyproject.toml | | |
| uv.lock | | uv.lock | | |
| View all files | | |

Repository files navigation

Mac Messages MCP

A Python bridge for interacting with the macOS Messages app using MCP (Multiple Context Protocol).

Features

• Read recent messages from the macOS Messages app
• Filter messages by contact
• Send new messages through iMessage
• Access messages via an API

Prerequisites

• macOS (tested on macOS 11+)
• Python 3.10+
• uv package manager

Installing uv

If you're on Mac, install uv using Homebrew:

brew install uv

Otherwise, follow the installation instructions on the uv website
.

⚠️ Do not proceed before installing uv

Installation

Full Disk Access Permission

⚠️ This application requires Full Disk Access permission for your terminal or application to access the Messages database.

To grant Full Disk Access:

1. Open System Preferences/Settings > Security & Privacy/Privacy > Full Disk Access
2. Click the lock icon to make changes
3. Add your terminal app (Terminal, iTerm2, etc.) or Claude Desktop/Cursor to the list
4. Restart your terminal or application after granting permission

Integration

Claude Desktop Integration

1. Go to Claude > Settings > Developer > Edit Config > claude_desktop_config.json
2. Add the following configuration:

{
    "mcpServers": {
        "messages": {
            "command": "uvx",
            "args": [\
                "mac-messages-mcp"\
            ]
        }
    }
}

Cursor Integration

Go to Cursor Settings > MCP and paste this as a command:

uvx mac-messages-mcp

⚠️ Only run one instance of the MCP server (either on Cursor or Claude Desktop), not both

Option 1: Install from PyPI

uv pip install mac-messages-mcp

Option 2: Install from source

# Clone the repository
git clone https://github.com/carterlasalle/mac_messages_mcp.git
cd mac_messages_mcp

# Install dependencies
uv install -e .

Usage

As a Module

from mac_messages_mcp import get_recent_messages, send_message

# Get recent messages
messages = get_recent_messages(hours=48)
print(messages)

# Send a message
result = send_message(recipient="+1234567890", message="Hello from Mac Messages MCP!")
print(result)

As a Command-Line Tool

# Run the MCP server directly
mac-messages-mcp

Development

Versioning

This project uses semantic versioning. See VERSIONING.md
for details on how the versioning system works and how to release new versions.

To bump the version:

python scripts/bump_version.py [patch|minor|major]

Security Notes

This application accesses the Messages database directly, which contains personal communications. Please use it responsibly and ensure you have appropriate permissions.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

About

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, group chat handling, and full support for sending and receiving messages.

pypi.org/project/mac-messages-mcp/

Topics

macos
mac
applescript
contacts
mcp
cursor
imessage
claude
mcp-server

Resources

Readme

License

MIT license

Activity

Stars

21 stars

Watchers

1 watching

Forks

1 fork

Report repository

Releases

12 tags

Packages 0

No packages published

Languages

• Python 100.0%

You can’t perform that action at this time.