# iMessage MCP

This project exposes a **read-only** MCP server for the local macOS Messages database.

## What it can do

- List recent chats
- Read messages from a chat
- Read messages by local date across all chats
- Search message text and subjects
- List attachments and local attachment paths
- Read text-like attachment contents
- Return attachments alongside messages
- Return server/database metadata

## What it cannot do

- Send messages
- Edit messages
- Delete messages
- Mark chats or messages as read/unread
- Modify attachment files

The SQLite connection is opened in `readonly` mode, and the server only exposes query tools.

## Attachment support

Use `list_attachments` to find attachments by chat or message. Use `read_attachment` with an `attachment_id` to read text-like files such as `.txt`, `.md`, `.csv`, `.json`, `.html`, `.rtf`, `.doc`, and `.docx`.

For PDFs and images, `read_attachment` also tries macOS Spotlight text metadata. If no text is available, binary files return metadata plus `resolved_path`. Import that path into AnythingLLM or use AnythingLLM's OCR/PDF pipeline to extract content.

`get_messages` returns attachment metadata under each message by default. Pass `include_attachment_content: true` to also extract readable attachment text inline with the message result.

Use `get_messages_by_date` for prompts such as "what messages did I send today?" Set `direction` to `sent`, `received`, or `all`. It returns message text and, when available, extracted attachment text inline.

## Attachment text cache

Successful attachment text extraction is cached under `cache/attachments`. The cache key includes the attachment ID, local file path, file size, modified time, and `max_bytes`, so changed files are reprocessed automatically.

`read_attachment` uses the cache by default. Set `use_cache: false` only when you intentionally want to force OCR/PDF extraction again.

## Run it

```bash
npm start
```

If your MCP client cannot find `sqlite3`, set:

```bash
export SQLITE3_PATH=/Users/lilty/miniconda3/bin/sqlite3
```

If your Messages database is in a different location, set:

```bash
export IMESSAGE_DB_PATH="$HOME/Library/Messages/chat.db"
```

## MCP client config

Use this in your MCP client configuration:

```json
{
  "mcpServers": {
    "imessage": {
      "command": "node",
      "args": ["/Users/lilty/Documents/Codex/2026-05-29/imessage-mcp/src/server.js"],
      "env": {
        "SQLITE3_PATH": "/Users/lilty/miniconda3/bin/sqlite3"
      }
    }
  }
}
```

## Notes

- On macOS, you may need to grant Full Disk Access to the app that launches the MCP server.
- The Messages database is read directly from `~/Library/Messages/chat.db`.