# wyattjoh/imessage-mcp [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/wyattjoh/imessage-mcp  
**GitHub Stars:** 29  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/wyattjoh-imessage-mcp

## Description
A Model Context Protocol server for reading iMessage data from macOS.

## Tools
Capabilities this server exposes over MCP:

- **search_messages** — Search messages with filters
- **get_recent_messages** — Get the most recent messages
- **get_chats** — List all conversations
- **get_handles** — Get all contacts/handles
- **get_messages_from_chat** — Get messages from a specific chat
- **search_contacts** — Search macOS Contacts by name and get phone numbers

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "imessage-mcp": {
    "command": "npx",
    "args": ["-y","wyattjoh-imessage-mcp"]
  }
}
```

## Documentation & README

# iMessage MCP

A Deno monorepo containing packages for iMessage access on macOS:

- **[@wyattjoh/imessage](https://github.com/wyattjoh/imessage-mcp/blob/HEAD/packages/imessage)** - Core library for read-only iMessage database access
- **[@wyattjoh/imessage-mcp](https://github.com/wyattjoh/imessage-mcp/blob/HEAD/packages/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`, or to a custom database configured with `IMESSAGE_DB_PATH`
- Read access to `~/Library/Application Support/AddressBook/` (for contacts search)

## Packages

### @wyattjoh/imessage

Core library for accessing iMessage data:

```bash
deno add @wyattjoh/imessage
```

```typescript
import { openMessagesDatabase, searchMessages } from "@wyattjoh/imessage";

const db = await openMessagesDatabase();
const results = await searchMessages(db, { query: "hello" });
db.close();
```

[See full documentation](https://github.com/wyattjoh/imessage-mcp/blob/HEAD/packages/imessage/README.md)

### @wyattjoh/imessage-mcp

MCP server for LLM integration:

```bash
# 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`:

```json
{
  "mcpServers": {
    "imessage": {
      "command": "deno",
      "args": [
        "run",
        "--allow-read",
        "--allow-env",
        "--allow-sys",
        "--allow-ffi",
        "jsr:@wyattjoh/imessage-mcp"
      ]
    }
  }
}
```

#### Custom Messages Database

Set `IMESSAGE_DB_PATH` to open a read-only SQLite database at another location, such as a periodically refreshed snapshot of `chat.db`:

```json
{
  "mcpServers": {
    "imessage": {
      "command": "deno",
      "args": [
        "run",
        "--allow-read",
        "--allow-env=IMESSAGE_DB_PATH",
        "--allow-sys",
        "--allow-ffi",
        "jsr:@wyattjoh/imessage-mcp"
      ],
      "env": {
        "IMESSAGE_DB_PATH": "/tmp/imessage-snapshot.sqlite"
      }
    }
  }
}
```

The process needs read access to the custom file. If Deno does not have permission to read `IMESSAGE_DB_PATH`, or the variable is empty or unset, the library uses `~/Library/Messages/chat.db` without prompting for environment access.

### Option 2: From Source

1. Clone this repository
2. Install dependencies:
   ```bash
   deno cache src/index.ts
   ```
3. 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

1. **search_messages** - Search messages with filters
   - `query` (optional): Text to search for
   - `handle` (optional): Phone number or email to filter by
   - `startDate` (optional): ISO datetime string for start date
   - `endDate` (optional): ISO datetime string for end date
   - `limit` (optional): Maximum results (1-200, default: 100)
   - `offset` (optional): Pagination offset (default: 0)

2. **get_recent_messages** - Get the most recent messages
   - `limit` (optional): Number of messages (1-100, default: 20)
   - `offset` (optional): Pagination offset (default: 0)

3. **get_chats** - List all conversations
   - `limit` (optional): Number of chats (1-200, default: 50)
   - `offset` (optional): Pagination offset (default: 0)

4. **get_handles** - Get all contacts/handles
   - `limit` (optional): Number of handles (1-200, default: 100)
   - `offset` (optional): Pagination offset (default: 0)

5. **get_messages_from_chat** - Get messages from a specific chat
   - `chatGuid` (required): The chat GUID
   - `limit` (optional): Number of messages (1-200, default: 50)
   - `offset` (optional): Pagination offset (default: 0)

6. **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 fields
   - `limit` (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:

```javascript
// 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:

```json
{
  "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.

```bash
# 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

```bash
# Work on @wyattjoh/imessage
cd packages/imessage
deno test --allow-read --allow-env --allow-ffi --allow-sys=homedir

# Work on @wyattjoh/imessage-mcp
cd packages/imessage-mcp
deno run --allow-read --allow-env --allow-sys --allow-ffi mod.ts
```

## License

MIT