# Imessage Mcp

> MCP server for reading and sending iMessages from Claude Code

- **Type:** MCP server
- **Install:** `agentstack add mcp-daveremy-imessage-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [daveremy](https://agentstack.voostack.com/s/daveremy)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [daveremy](https://github.com/daveremy)
- **Source:** https://github.com/daveremy/imessage-mcp

## Install

```sh
agentstack add mcp-daveremy-imessage-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# imessage-mcp

An [MCP server](https://modelcontextprotocol.io/) that gives AI assistants like [Claude Code](https://docs.anthropic.com/en/docs/claude-code) the ability to read and send iMessages on macOS.

Phone numbers and email addresses are automatically resolved to real names from your Apple Contacts — so you interact with people, not handles.

## What it looks like

```
> imessage-mcp chats 3

1. Sarah, Mike, Pete, Joel
   Chat ID: 91 | iMessage, 4 participants | 46 messages | Mar 15, 9:33 PM
2. Family Group Chat
   Chat ID: 40 | iMessage, 8 participants | 125 messages | Mar 15, 6:08 PM
3. Alex Johnson (+15551234567)
   Chat ID: 67 | iMessage | 12 messages | Mar 15, 4:39 PM
```

```
> imessage-mcp messages 67 3

[Mar 15, 2:01 PM] Alex Johnson (+15551234567): Are we still on for Friday?
[Mar 15, 2:05 PM] Me: Yes! Looking forward to it.
[Mar 15, 4:39 PM] Alex Johnson (+15551234567): Great, see you then!
```

## Prerequisites

**macOS only.** This reads the local Messages database directly.

1. **Full Disk Access** — your terminal app needs permission to read `~/Library/Messages/chat.db`
   - System Settings → Privacy & Security → Full Disk Access → add your terminal (Terminal.app, iTerm2, Ghostty, etc.)
   - Restart the terminal after granting access
2. **Contacts permission** (optional but recommended) — for resolving phone numbers to names
   - If names aren't showing up, grant Contacts access to your terminal app in System Settings
3. **Messages.app signed in** — required only for sending messages
4. **Node.js >= 22** — uses the built-in `node:sqlite` module (no native compilation needed)

Run `imessage-mcp status` to verify everything is working.

## Installation

### Claude Code plugin (recommended)

Install directly from this repo:

```bash
claude plugin add daveremy/imessage-mcp
```

Or from the [daveremy-plugins marketplace](https://github.com/daveremy/claude-plugins) (includes all daveremy plugins):

```bash
claude plugin add daveremy/claude-plugins --name imessage-mcp
```

Restart Claude Code and the `im_*` tools will appear automatically.

### Manual MCP config

Alternatively, add to your project's `.mcp.json` or `~/.claude/mcp.json`:

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

### As a CLI tool

```bash
npx @daveremy/imessage-mcp status       # verify access
npx @daveremy/imessage-mcp chats        # list recent conversations
npx @daveremy/imessage-mcp messages 42  # read messages from chat 42
```

## Tools

### im_status

Check that database access and contact resolution are working.

```
Messages database: OK
  Chats: 102
  Messages: 1432

Contacts: OK (77 contacts)
```

### im_chats

List recent conversations, ordered by last activity. Groups show the group name or resolved participant names. 1:1 chats show the contact name with handle.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | number | 20 | Maximum chats to return |

### im_messages

Read messages from a specific chat in chronological order. Includes reactions, attachments, edited/unsent indicators, and pagination.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `chatId` | number | required | Chat ID from `im_chats` |
| `limit` | number | 50 | Messages per page |
| `cursor` | string | — | Opaque cursor from previous response for loading older messages |

Messages are formatted as:
```
[Mar 15, 2:01 PM] Contact Name (+15551234567): message text
[Mar 15, 2:05 PM] Me: response text
[Mar 15, 2:06 PM] Me: [Liked "message text"]
[Mar 15, 2:07 PM] Contact Name (+15551234567): photo.jpg [Attachment: photo.jpg, 2.1 MB]
```

### im_search

Search message text across all chats or within a specific chat. Scans up to 5,000 recent messages with case-insensitive substring matching.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | string | required | Text to search for |
| `chatId` | number | — | Limit search to one chat |
| `limit` | number | 20 | Maximum results |

Results include a completeness line: `(searched 1432 of 1432 total messages)` so you know the coverage.

### im_send

Send a message to an existing chat. The MCP tool description includes a warning to always confirm with the user before sending.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `chatId` | number | required | Chat ID from `im_chats` |
| `text` | string | required | Message text |

Uses JXA (JavaScript for Automation) to send via Messages.app. Only targets existing chat threads by GUID — never creates new conversations.

### im_participants

List everyone in a chat with resolved contact names and service type (iMessage, SMS, RCS).

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `chatId` | number | required | Chat ID from `im_chats` |

## How it works

```
┌─────────────┐     stdio/JSON-RPC      ┌──────────────┐
│ Claude Code  │ ◄──────────────────────► │ imessage-mcp │
└─────────────┘                          └──────┬───────┘
                                                │
                         ┌──────────────────────┼──────────────────────┐
                         │                      │                      │
                         ▼                      ▼                      ▼
              ~/Library/Messages/     AddressBook/*.abcddb      osascript (JXA)
                  chat.db                (read-only)           Messages.app
                (read-only)           Contact resolution         (send)
              Message history
```

- **Reading**: Queries `chat.db` directly via SQLite (read-only). Message text is extracted from the `attributedBody` column using a custom binary parser for Apple's typedstream format (NSArchiver), falling back to the `text` column.
- **Contacts**: Reads Apple's AddressBook SQLite databases to build a phone/email → name lookup map. Phone numbers are normalized for matching (strips formatting, handles US country code).
- **Sending**: Invokes Messages.app through JXA (`osascript -l JavaScript`). Message text is safely encoded via `JSON.stringify()`. Only targets existing conversations by chat GUID.

## CLI reference

```
imessage-mcp                                      Start MCP server (stdio)
imessage-mcp status                               Check database access
imessage-mcp chats [limit]                        List recent chats
imessage-mcp messages  [limit] [cursor]   Read messages
imessage-mcp search  [chatId] [limit]      Search messages
imessage-mcp participants                  List participants
imessage-mcp send                    Send a message
```

## Development

```bash
git clone https://github.com/daveremy/imessage-mcp.git
cd imessage-mcp
npm install
npm run build

# Test directly
npx tsx src/cli.ts status
npx tsx src/cli.ts chats

# Test as MCP server
npx @modelcontextprotocol/inspector -- npx tsx src/mcp.ts
```

### Project structure

```
src/
  mcp.ts              MCP server entry (stdio transport, tool registration)
  cli.ts              CLI entry (argument parsing, dual-mode)
  db.ts               SQLite queries against ~/Library/Messages/chat.db
  contacts.ts         Contact resolution from AddressBook databases
  typedstream.ts      Binary parser for attributedBody (NSArchiver format)
  applescript.ts      Send messages via JXA → Messages.app
  types.ts            TypeScript interfaces
  version.ts          Version from package.json
  tools/
    status.ts         im_status implementation
    chats.ts          im_chats implementation
    messages.ts       im_messages implementation
    search.ts         im_search implementation
    send.ts           im_send implementation
    participants.ts   im_participants implementation
```

## Known limitations

- **Phone normalization is US-centric**: 10-digit numbers get a "1" prefix. International numbers with different country code lengths may not resolve to contacts.
- **Typedstream parser is best-effort**: Handles the common single-string NSAttributedString. Multi-segment bodies, inline attachment references, or unusual class hierarchies return `(no text content)`.
- **Attachments are metadata only**: Filenames and sizes are shown, but attachment file contents are not read or returned.
- **Search scans recent messages**: Up to 5,000 most recent messages, not the full history. The completeness line tells you exactly how much was covered.
- **No conversation creation**: `im_send` only sends to existing chats. It cannot start new conversations.

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [daveremy](https://github.com/daveremy)
- **Source:** [daveremy/imessage-mcp](https://github.com/daveremy/imessage-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-daveremy-imessage-mcp
- Seller: https://agentstack.voostack.com/s/daveremy
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.