iMessage MCP
MCP server enabling LLM integration with macOS iMessage data.
Key Features
Use Cases
README
iMessage MCP
A Deno monorepo containing packages for iMessage access on macOS:
- @wyattjoh/imessage - Core library for read-only iMessage database access
- @wyattjoh/imessage-mcp - Model Context Protocol (MCP) server for LLM integration
Features
- Search messages by text content, contact, or date range
- Get recent messages
- List all chats/conversations
- Get all contacts/handles
- Retrieve messages from specific chats
- Search macOS Contacts by name with iMessage handle ID correlation
Requirements
- macOS (iMessage is only available on macOS)
- Deno 2.x or later
- Read access to
~/Library/Messages/chat.db - Read access to
~/Library/Application Support/AddressBook/(for contacts search)
Packages
@wyattjoh/imessage
Core library for accessing iMessage data:
deno add @wyattjoh/imessage
import { openMessagesDatabase, searchMessages } from "@wyattjoh/imessage";
const db = await openMessagesDatabase();
const results = await searchMessages(db, { query: "hello" });
db.close();
@wyattjoh/imessage-mcp
MCP server for LLM integration:
# Run directly from JSR
deno run --allow-read --allow-env --allow-sys --allow-ffi jsr:@wyattjoh/imessage-mcp
# Or install globally
deno install --global --allow-read --allow-env --allow-sys --allow-ffi -n imessage-mcp jsr:@wyattjoh/imessage-mcp
For Claude Desktop app integration, add this to your claude_desktop_config.json:
{
"mcpServers": {
"imessage": {
"command": "deno",
"args": [
"run",
"--allow-read",
"--allow-env",
"--allow-sys",
"--allow-ffi",
"jsr:@wyattjoh/imessage-mcp"
]
}
}
}
Option 2: From Source
- Clone this repository
- Install dependencies:
bash
deno cache src/index.ts - Run the server:
bash
deno run --allow-read --allow-env --allow-sys --allow-ffi src/index.ts # Or use the task: deno task start
Available Tools
-
search_messages - Search messages with filters
query(optional): Text to search forhandle(optional): Phone number or email to filter bystartDate(optional): ISO datetime string for start dateendDate(optional): ISO datetime string for end datelimit(optional): Maximum results (1-200, default: 100)offset(optional): Pagination offset (default: 0)
-
get_recent_messages - Get the most recent messages
limit(optional): Number of messages (1-100, default: 20)offset(optional): Pagination offset (default: 0)
-
get_chats - List all conversations
limit(optional): Number of chats (1-200, default: 50)offset(optional): Pagination offset (default: 0)
-
get_handles - Get all contacts/handles
limit(optional): Number of handles (1-200, default: 100)offset(optional): Pagination offset (default: 0)
-
get_messages_from_chat - Get messages from a specific chat
chatGuid(required): The chat GUIDlimit(optional): Number of messages (1-200, default: 50)offset(optional): Pagination offset (default: 0)
-
search_contacts - Search macOS Contacts by name and get phone numbers
firstName(required): First name to search for (e.g., 'John')lastName(optional): Last name to search for (e.g., 'Smith'). If omitted, searches across all name fieldslimit(optional): Maximum results (1-200, default: 50)offset(optional): Pagination offset (default: 0)- Returns contact info with phone numbers and email addresses that can be used as handle parameters
- Searches directly in the macOS AddressBook database for better performance and reliability
Pagination Examples
All tools now support pagination using limit and offset parameters and return pagination metadata:
// Get first 20 recent messages
get_recent_messages({ limit: 20, offset: 0 });
// Get next 20 recent messages (page 2)
get_recent_messages({ limit: 20, offset: 20 });
// Get first 10 chats
get_chats({ limit: 10, offset: 0 });
// Get messages 51-100 from a specific chat
get_messages_from_chat({
chatGuid: "iMessage;-;+15551234",
limit: 50,
offset: 50,
});
// Search with pagination
search_messages({
query: "meeting",
limit: 100,
offset: 200,
});
// Search contacts with pagination
search_contacts({
firstName: "John",
lastName: "Smith",
limit: 50,
offset: 0,
});
Response Format with Pagination Metadata
All paginated tools now return responses in this format:
{
"data": [
// Array of results (messages, chats, handles, etc.)
],
"pagination": {
"total": 1250, // Total number of results available
"limit": 100, // Current page size
"offset": 200, // Current offset
"hasMore": true, // Whether there are more results to fetch
"page": 3, // Current page number (1-indexed)
"totalPages": 13 // Total number of pages
}
}
This metadata helps you:
- Know the total number of results without fetching all of them
- Determine if there are more pages to fetch (
hasMore) - Calculate which page you're on and how many pages exist
- Build proper pagination UI components
Security Notes
- This server runs with read-only access to the iMessage database
- No messages can be sent or modified
- The server only accesses local data
Development
This is a Deno workspace monorepo. All commands run from the root affect all packages.
# Clone the repository
git clone https://github.com/wyattjoh/imessage-mcp.git
cd imessage-mcp
# Cache dependencies
deno cache packages/*/mod.ts
# Format all code
deno task fmt
# Lint all packages
deno task lint
# Type check all packages
deno task check
# Run tests
deno task test
# Run MCP server locally
cd packages/imessage-mcp
deno run --allow-read --allow-env --allow-sys --allow-ffi mod.ts
# Publish packages (CI/CD)
deno publish
Working on Individual Packages
# Work on @wyattjoh/imessage
cd packages/imessage
deno test --allow-read --allow-env --allow-ffi
# Work on @wyattjoh/imessage-mcp
cd packages/imessage-mcp
deno run --allow-read --allow-env --allow-sys --allow-ffi mod.ts
License
MIT
Star History
Repository Owner
User
Repository Details
Programming Languages
Tags
Join Our Newsletter
Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.
Related MCPs
Discover similar Model Context Protocol servers
MCP Server for Iaptic
A Model Context Protocol server for accessing and managing Iaptic data with AI agents.
MCP Server for Iaptic implements the Model Context Protocol to enable AI models, such as Claude, to securely and efficiently interact with Iaptic's customer, purchase, transaction, and statistics data. The server provides a standardized interface and command set for querying and managing information related to customers, purchases, transactions, events, and application management. Designed for integration with Claude Desktop and similar AI clients, it offers both automated and manual installation options.
- ⭐ 5
- MCP
- iaptic/mcp-server-iaptic
Raindrop.io MCP Server
Enable LLMs to manage and search Raindrop.io bookmarks via the Model Context Protocol.
Raindrop.io MCP Server is an integration that allows large language models to interact with Raindrop.io bookmarks using the Model Context Protocol. It provides tools to create and search bookmarks, including filtering by tags, and is designed for interoperability with environments like Claude for Desktop. Installation can be done via Smithery or manually, and configuration is managed through environment variables. The project is open source and optimized for secure, tokenized access to Raindrop.io.
- ⭐ 63
- MCP
- hiromitsusasaki/raindrop-io-mcp-server
MCP-Typescribe
An MCP server for serving TypeScript API context to language models.
MCP-Typescribe is an open-source implementation of the Model Context Protocol (MCP) focused on providing LLMs with contextual, real-time access to TypeScript API documentation. It parses TypeScript (and other) definitions using TypeDoc-generated JSON and serves this information via a queryable server that supports tools used by AI coding assistants. The solution enables AI agents to dynamically explore, search, and understand unknown APIs, accelerating onboarding and supporting agentic behaviors in code generation.
- ⭐ 45
- MCP
- yWorks/mcp-typescribe
Bear MCP Server
MCP server for accessing and searching Bear Notes on macOS.
Bear MCP Server is an implementation of the Model Context Protocol that provides programmatic access to notes and tags stored in Bear Notes on macOS. It enables users to read, search, and list notes and tags via standardized MCP tools. The server connects to Bear's SQLite database and exposes essential commands for integration with AI models and workflows.
- ⭐ 40
- MCP
- akseyh/bear-mcp-server
mcp-server-chatsum
Summarize and query chat messages using the MCP Server protocol.
mcp-server-chatsum is an MCP Server designed to summarize and query chat messages. It provides tools to interact with chat data, enabling users to extract and summarize message content based on specified prompts. The server can be integrated with Claude Desktop and supports communication over stdio, offering dedicated debugging tools via the MCP Inspector. Environment variable support and database integration ensure flexible deployment for chat data management.
- ⭐ 1,024
- MCP
- chatmcp/mcp-server-chatsum
Apple Books MCP
Model Context Protocol server for integrating and managing Apple Books data with AI assistants.
Apple Books MCP is a server implementation of the Model Context Protocol (MCP) that enables AI assistants to access, organize, and interact with Apple Books data such as collections, books, highlights, notes, and annotations. It provides standardized tools for retrieving and searching book-related data, supporting integration with platforms like Claude Desktop. Designed for easy setup with Python or uv, it facilitates context-aware AI capabilities for reading and annotation workflows.
- ⭐ 33
- MCP
- vgnshiyer/apple-books-mcp
Didn't find tool you were looking for?