imessage-query-fastmcp-mcp-server

This project is an MCP server that provides safe access to the iMessage database. Built with the FastMCP framework and the imessagedb library, it enables proper phone number validation and automatic macOS permission handling. This allows LLMs to query and analyze iMessage conversations effectively.

GitHub Stars

68

User Rating

Not Rated

Favorites

0

Views

19

Forks

13

Issues

3

Installation
Difficulty
Intermediate
Estimated Time
10-20 minutes
Requirements
macOS
Python 3.12+
+1 more

Installation

Installation

Prerequisites

macOS: Required for iMessage database access
Python 3.12 or higher: Required for modern type hints
uv: Modern Python package manager
Full Disk Access permission: For your MCP client (Claude Desktop, Cursor, VS Code, etc.)

Installation Steps

1. Clone Repository

bash
git clone https://github.com/hannesrudolph/imessage-query-fastmcp-mcp-server.git
cd imessage-query-fastmcp-mcp-server

2. Install uv

bash

Install uv using Homebrew (recommended)

brew install uv

Or install using the official installer

curl -LsSf https://astral.sh/uv/install.sh | sh

Troubleshooting

Common Issues

Issue: Server won't start Solution: Check Python version and ensure dependencies are installed correctly.

Configuration

Configuration

Basic Configuration

Claude Desktop Setup

Edit ~/.config/claude-desktop/claude_desktop_config.json:
json
{
  "mcpServers": {
    "imessage-query": {
      "command": "python",
      "args": ["-m", "server"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

Environment Variables

Set the following environment variables as needed:
bash
export API_KEY="your-api-key"
export DEBUG="true"

Configuration Example

json
{
  "mcpServers": {
    "imessage-query": {
      "command": "python",
      "args": ["-m", "server"],
      "env": {
        "PORT": "3000",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Examples

Examples

Basic Usage

Programmatic Usage

python
import requests

def call_mcp_tool(tool_name, params):
    response = requests.post(
        'http://localhost:3000/mcp/call',
        json={
            'tool': tool_name,
            'parameters': params
        }
    )
    return response.json()

Usage example

result = call_mcp_tool('get_chat_transcript', { 'phone_number': '+1234567890', 'start_date': '2023-01-01', 'end_date': '2023-01-31' }) print(result)

Advanced Examples

Automation Script

bash
#!/bin/bash

Batch processing example

for file in *.txt; do mcp-tool process "$file" done

Use Cases

Retrieving message history for a specific phone number
Analyzing past iMessage conversations
Aggregating messages over a specific period
Automating iMessage data processing using LLMs

Additional Resources