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 - Search messages by text content, contact, or date range - Get recent messages - List all chats/conversations - Get all contacts/handles - Retrieve messages from specific chat
Add this skill
npx mdskills install wyattjoh/imessage-mcpWell-documented MCP server providing read-only iMessage access with comprehensive pagination support
1# iMessage MCP23A Deno monorepo containing packages for iMessage access on macOS:45- **[@wyattjoh/imessage](packages/imessage)** - Core library for read-only iMessage database access6- **[@wyattjoh/imessage-mcp](packages/imessage-mcp)** - Model Context Protocol (MCP) server for LLM integration78## Features910- Search messages by text content, contact, or date range11- Get recent messages12- List all chats/conversations13- Get all contacts/handles14- Retrieve messages from specific chats15- Search macOS Contacts by name with iMessage handle ID correlation1617## Requirements1819- macOS (iMessage is only available on macOS)20- Deno 2.x or later21- Read access to `~/Library/Messages/chat.db`22- Read access to `~/Library/Application Support/AddressBook/` (for contacts search)2324## Packages2526### @wyattjoh/imessage2728Core library for accessing iMessage data:2930```bash31deno add @wyattjoh/imessage32```3334```typescript35import { openMessagesDatabase, searchMessages } from "@wyattjoh/imessage";3637const db = await openMessagesDatabase();38const results = await searchMessages(db, { query: "hello" });39db.close();40```4142[See full documentation](packages/imessage/README.md)4344### @wyattjoh/imessage-mcp4546MCP server for LLM integration:4748```bash49# Run directly from JSR50deno run --allow-read --allow-env --allow-sys --allow-ffi jsr:@wyattjoh/imessage-mcp5152# Or install globally53deno install --global --allow-read --allow-env --allow-sys --allow-ffi -n imessage-mcp jsr:@wyattjoh/imessage-mcp54```5556For Claude Desktop app integration, add this to your `claude_desktop_config.json`:5758```json59{60 "mcpServers": {61 "imessage": {62 "command": "deno",63 "args": [64 "run",65 "--allow-read",66 "--allow-env",67 "--allow-sys",68 "--allow-ffi",69 "jsr:@wyattjoh/imessage-mcp"70 ]71 }72 }73}74```7576### Option 2: From Source77781. Clone this repository792. Install dependencies:80 ```bash81 deno cache src/index.ts82 ```833. Run the server:84 ```bash85 deno run --allow-read --allow-env --allow-sys --allow-ffi src/index.ts86 # Or use the task:87 deno task start88 ```8990### Available Tools91921. **search_messages** - Search messages with filters93 - `query` (optional): Text to search for94 - `handle` (optional): Phone number or email to filter by95 - `startDate` (optional): ISO datetime string for start date96 - `endDate` (optional): ISO datetime string for end date97 - `limit` (optional): Maximum results (1-200, default: 100)98 - `offset` (optional): Pagination offset (default: 0)991002. **get_recent_messages** - Get the most recent messages101 - `limit` (optional): Number of messages (1-100, default: 20)102 - `offset` (optional): Pagination offset (default: 0)1031043. **get_chats** - List all conversations105 - `limit` (optional): Number of chats (1-200, default: 50)106 - `offset` (optional): Pagination offset (default: 0)1071084. **get_handles** - Get all contacts/handles109 - `limit` (optional): Number of handles (1-200, default: 100)110 - `offset` (optional): Pagination offset (default: 0)1111125. **get_messages_from_chat** - Get messages from a specific chat113 - `chatGuid` (required): The chat GUID114 - `limit` (optional): Number of messages (1-200, default: 50)115 - `offset` (optional): Pagination offset (default: 0)1161176. **search_contacts** - Search macOS Contacts by name and get phone numbers118 - `firstName` (required): First name to search for (e.g., 'John')119 - `lastName` (optional): Last name to search for (e.g., 'Smith'). If omitted, searches across all name fields120 - `limit` (optional): Maximum results (1-200, default: 50)121 - `offset` (optional): Pagination offset (default: 0)122 - Returns contact info with phone numbers and email addresses that can be used as handle parameters123 - Searches directly in the macOS AddressBook database for better performance and reliability124125### Pagination Examples126127All tools now support pagination using `limit` and `offset` parameters and return pagination metadata:128129```javascript130// Get first 20 recent messages131get_recent_messages({ limit: 20, offset: 0 });132133// Get next 20 recent messages (page 2)134get_recent_messages({ limit: 20, offset: 20 });135136// Get first 10 chats137get_chats({ limit: 10, offset: 0 });138139// Get messages 51-100 from a specific chat140get_messages_from_chat({141 chatGuid: "iMessage;-;+15551234",142 limit: 50,143 offset: 50,144});145146// Search with pagination147search_messages({148 query: "meeting",149 limit: 100,150 offset: 200,151});152153// Search contacts with pagination154search_contacts({155 firstName: "John",156 lastName: "Smith",157 limit: 50,158 offset: 0,159});160```161162#### Response Format with Pagination Metadata163164All paginated tools now return responses in this format:165166```json167{168 "data": [169 // Array of results (messages, chats, handles, etc.)170 ],171 "pagination": {172 "total": 1250, // Total number of results available173 "limit": 100, // Current page size174 "offset": 200, // Current offset175 "hasMore": true, // Whether there are more results to fetch176 "page": 3, // Current page number (1-indexed)177 "totalPages": 13 // Total number of pages178 }179}180```181182This metadata helps you:183184- Know the total number of results without fetching all of them185- Determine if there are more pages to fetch (`hasMore`)186- Calculate which page you're on and how many pages exist187- Build proper pagination UI components188189## Security Notes190191- This server runs with read-only access to the iMessage database192- No messages can be sent or modified193- The server only accesses local data194195## Development196197This is a Deno workspace monorepo. All commands run from the root affect all packages.198199```bash200# Clone the repository201git clone https://github.com/wyattjoh/imessage-mcp.git202cd imessage-mcp203204# Cache dependencies205deno cache packages/*/mod.ts206207# Format all code208deno task fmt209210# Lint all packages211deno task lint212213# Type check all packages214deno task check215216# Run tests217deno task test218219# Run MCP server locally220cd packages/imessage-mcp221deno run --allow-read --allow-env --allow-sys --allow-ffi mod.ts222223# Publish packages (CI/CD)224deno publish225```226227### Working on Individual Packages228229```bash230# Work on @wyattjoh/imessage231cd packages/imessage232deno test --allow-read --allow-env --allow-ffi233234# Work on @wyattjoh/imessage-mcp235cd packages/imessage-mcp236deno run --allow-read --allow-env --allow-sys --allow-ffi mod.ts237```238239## License240241MIT242
Full transparency — inspect the skill content before installing.