# bluebubbles-mcp

MCP server for [BlueBubbles](https://bluebubbles.app) — access iMessage from any MCP client.

Built from scratch with no third-party MCP dependencies beyond the official [`mcp`](https://pypi.org/project/mcp/) SDK and [`httpx`](https://pypi.org/project/httpx/).

## Prerequisites

- Python 3.11+
- A running [BlueBubbles server](https://bluebubbles.app) with API access enabled

## Setup

```bash
git clone https://github.com/metaember/bluebubbles-mcp.git
cd bluebubbles-mcp
uv sync
```

## Configuration

Add to your MCP client config (e.g. Claude Code `~/.claude/settings.json`):

```json
{
  "mcpServers": {
    "bluebubbles": {
      "command": "uv",
      "args": ["--directory", "/path/to/bluebubbles-mcp", "run", "python", "-m", "bb_mcp.server"],
      "env": {
        "BLUEBUBBLES_URL": "https://your-bluebubbles-server",
        "BLUEBUBBLES_PASSWORD": "your-server-password"
      }
    }
  }
}
```

### Restricting write recipients (allowlist)

By default the server can message anyone. Set `BLUEBUBBLES_WRITE_ALLOWLIST` to a
comma-separated list of phone numbers and/or emails to restrict **every write**
(send, reaction, attachment, typing, scheduling, group edits, delete/leave) to
those recipients. It is enforced server-side, so an MCP client — including one
reaching the HTTP transport — cannot bypass it.

```jsonc
"BLUEBUBBLES_WRITE_ALLOWLIST": "+15551234567, partner@example.com",
"BLUEBUBBLES_ALLOWLIST_REGION": "US"  // optional, default region for parsing local numbers
```

Behavior:

- **Unset** → unrestricted (backward compatible). **Set but empty** (`""`) → deny
  all, a safe failure mode.
- Numbers are matched in normalized E.164 form, so `(555) 123-4567` and
  `+15551234567` are equivalent; emails match case-insensitively.
- For a **group chat**, *every* participant must be on the list or the write is
  blocked. A chat whose participants can't be resolved is denied (fail-closed).
- Read tools are **not** restricted, and the message-GUID writes
  (`edit_message`, `unsend_message`) aren't covered — they only act on an
  already-sent message and can't reach a new recipient. A
  `BLUEBUBBLES_READ_ALLOWLIST` may be added later.

### Private API vs AppleScript

BlueBubbles can drive Messages two ways. **AppleScript** works on any install
with no extra setup but only sends plain texts/attachments. The **[Private
API](https://docs.bluebubbles.app/private-api/installation)** (requires the
BlueBubbles Helper + partially disabled SIP) additionally unlocks tapbacks,
edit/unsend, typing indicators, read receipts, group management, threaded
replies, and SMS sending.

On startup the server reads `/server/info` and adapts itself to what's actually
available:

- **Sends** use the Private API when present, and fall back to AppleScript when
  not — so `send_message` works on a bare install instead of erroring.
- **Tools that require the Private API** (reactions, edit/unsend, typing,
  read receipts, group management, iMessage/FaceTime availability checks) are
  **hidden from the tool list** when it's unavailable, so a client never sees a
  tool that could only fail.

Override the auto-detection with `BLUEBUBBLES_PRIVATE_API`:

```jsonc
"BLUEBUBBLES_PRIVATE_API": "auto"   // default: introspect /server/info
// "true"  — force-enable (assume the Private API is set up)
// "false" — force-disable (AppleScript only; hide Private API tools)
```

If `/server/info` can't be read at startup, detection fails open (assumes the
Private API is available) so a transient blip doesn't hide half the toolset.

The same `/server/info` read also discovers the user's own iMessage address,
surfaced by the `get_my_address` tool. Override it if detection is wrong or you
run multiple handles:

```jsonc
"BLUEBUBBLES_MY_ADDRESS": "+15551234567"  // or you@icloud.com
```

### Contact names

Message and chat data from BlueBubbles carries raw phone numbers and emails, not
names. To save the model from constantly cross-referencing numbers, read
responses are **enriched with a `contactName`** beside each handle, and
`find_contact` / `find_chats` let it reach people by name instead of number.

Resolution is lazy and cached per session: a response's addresses are looked up
in a single batched `/contact/query` the first time they're seen, then reused.
Disable it (for leaner responses or if your contact DB is slow) with:

```jsonc
"BLUEBUBBLES_RESOLVE_NAMES": "false"  // default: enabled
```

`find_contact` / `find_chats` still work when this is off — they're explicit.

### Freshness guard

An agent can reply to a conversation against a stale snapshot — it read the thread
a while ago, a new message arrived in the gap, and it answers without seeing it.
The freshness guard enforces, server-side and per agent, that a send into a chat
only goes through if that agent **read the chat within the last hour and nothing
new has arrived since**. (A consequence: you must read an existing chat before
sending into it — good hygiene for replies. Starting a brand-new conversation via
`create_chat` is unaffected; it's for first contact only and, with the guard on,
refuses to reach an existing chat — use `send_message` for those.)

**How it works.** The guard keeps a per-agent *watermark* — the newest message each
agent has seen in each chat (optimistic concurrency, like an `ETag` on the thread):

- Reading a chat with `get_chat_messages` records the watermark. Only that tool
  records — a scan like `get_unread_chats` doesn't — so to reply you must
  deliberately open the actual thread.
- Before a send, the server re-checks the chat's live newest message. If anything
  (from anyone — the other person, you on another device, or another agent) arrived
  since your watermark, or your read is older than the TTL, the send is **blocked**
  with a note to re-read and re-plan.
- Your own send advances your watermark, so sending doesn't block your next send.

See [`docs/freshness-guard.md`](docs/freshness-guard.md) for the full design.

**On by default.** Disable with `BLUEBUBBLES_FRESHNESS=off`. Tuning:

```jsonc
"BLUEBUBBLES_FRESHNESS": "off",                  // default: on
"BLUEBUBBLES_FRESHNESS_IDENTITY": "session",     // how agents are told apart (default)
"BLUEBUBBLES_WATERMARK_TTL_SECONDS": "3600",     // how long a read stays "fresh" (default 1h)
"BLUEBUBBLES_WATERMARK_MAX_AGENTS": "10000"      // memory backstop (default 10000)
```

The freshness check is *per agent*, so it needs to tell agents apart.
`BLUEBUBBLES_FRESHNESS_IDENTITY` selects how:

- **`session`** (default): use the MCP transport session — automatic and
  zero-config for **stdio** (one agent) and **direct HTTP** (one session per
  connecting client). Over HTTP this relies on stateful sessions (FastMCP's
  default); the server **refuses to start** if you combine session-identity
  freshness with stateless HTTP, since every send would be blocked.
- **`meta`**: identify agents by a per-agent `agentId` the caller stamps into
  request `_meta`. Required only behind a **pooling proxy/airlock**, where every
  agent shares one transport session so `session` can't distinguish them. See
  [`docs/freshness-guard.md`](docs/freshness-guard.md) for the airlock contract.

### Compact responses & sender filtering

Message reads return a **compact projection by default** — the fields an
assistant needs (`guid`, `text`, `handle` + `contactName`, `isFromMe`,
timestamps, attachment names, reaction/reply linkage) instead of the full raw
BlueBubbles objects, which cuts token usage substantially. Pass `extended=true`
on any read tool to get the complete raw fields.

Message reads (`get_chat_messages`, `search_messages`, `get_recent_messages`)
also accept **`from_address`** to filter by who sent each message — pass a phone
number / email, or `"me"` for the user's own messages. Filtering is by true
sender (the user when `isFromMe`, otherwise the message's handle), so it's
correct in both 1:1 and group chats.

## Tools

| Tool | Description | Annotations |
|------|-------------|-------------|
| `ping` | Check server connectivity | read-only |
| `get_server_info` | Server info and health | read-only |
| `get_my_address` | The user's own iMessage address (to identify their own messages) | read-only |
| `list_chats` | List conversations by recent activity | read-only |
| `get_chat` | Chat details with participants | read-only |
| `get_chat_messages` | Messages from a chat | read-only |
| `search_messages` | Search by text, chat, time range | read-only |
| `get_message` | Single message by GUID | read-only |
| `get_contacts` | All contacts | read-only |
| `lookup_contact` | Look up name by phone/email | read-only |
| `find_contact` | Find contacts by name (phone/email unknown) | read-only |
| `find_chats` | Find chats involving a contact by name | read-only |
| `check_imessage` | Check iMessage registration | read-only |
| `check_facetime` | Check FaceTime registration | read-only |
| `query_handles` | List/search known handles | read-only |
| `get_handle` | Get a handle by address | read-only |
| `get_focus_status` | Contact's Focus / Do Not Disturb status | read-only |
| `find_my_devices` | Find My — your devices' locations | read-only |
| `find_my_friends` | Find My — friends' locations | read-only |
| `list_scheduled_messages` | List future messages | read-only |
| `get_scheduled_message` | Get one scheduled message by ID | read-only |
| `get_recent_messages` | Messages from last N minutes across all chats | read-only |
| `get_unread_chats` | Chats with unread messages + their latest messages | read-only |
| `get_attachment_info` | Attachment metadata | read-only |
| `download_attachment` | Download attachment as base64 | read-only |
| `get_group_icon` | Download a group chat's icon | read-only |
| `mark_chat_read` | Send read receipt | idempotent, open-world |
| `mark_chat_unread` | Mark chat unread (local) | idempotent |
| `rename_group` | Rename a group chat | idempotent |
| `set_group_icon` | Set a group chat's icon | idempotent |
| `start_typing` | Show typing indicator | open-world |
| `stop_typing` | Stop typing indicator | open-world |
| `send_message` | Send to an existing chat (1:1 or group) | open-world |
| `create_chat` | Start a new 1:1 conversation by phone/email | open-world |
| `create_group_chat` | Create a group chat + first message | open-world |
| `send_attachment` | Send a file attachment | open-world |
| `send_multipart` | Send text + attachments as one message | open-world |
| `send_reaction` | Tapback reaction | open-world |
| `edit_message` | Edit a sent message | open-world |
| `schedule_message` | Schedule a future message | open-world |
| `update_scheduled_message` | Update a scheduled message | open-world |
| `add_participant` | Add to group chat | open-world |
| `unsend_message` | Retract a message | destructive, open-world |
| `remove_participant` | Remove from group chat | destructive, open-world |
| `leave_chat` | Leave a group chat | destructive, open-world |
| `remove_group_icon` | Remove a group chat's icon | destructive, open-world |
| `delete_message` | Delete a single message | destructive, open-world |
| `delete_chat` | Delete a conversation | destructive, open-world |
| `delete_scheduled_message` | Cancel scheduled message | destructive, open-world |

## Run over HTTP (Docker)

The server speaks stdio by default. Set `MCP_TRANSPORT=streamable-http` to serve
over [Streamable HTTP](https://modelcontextprotocol.io) instead, so any
HTTP-capable MCP client can connect at `http://<host>:8000/mcp`. The Docker image
sets this for you.

```sh
docker build -t bluebubbles-mcp .
docker run --rm -e BLUEBUBBLES_URL -e BLUEBUBBLES_PASSWORD -p 8000:8000 bluebubbles-mcp
```

As a Compose service — credentials live in this container's own environment (an
`env_file` or Docker secrets), so they stay isolated to this tool:

```yaml
services:
  bluebubbles-mcp:
    build: .
    environment:
      BLUEBUBBLES_URL: ${BLUEBUBBLES_URL}
      BLUEBUBBLES_PASSWORD: ${BLUEBUBBLES_PASSWORD}
    restart: unless-stopped
```

Notes:
- The HTTP endpoint is unauthenticated, so don't expose it publicly — keep it on a
  private/internal network (and drop the published `ports:` if a co-located client
  reaches it over the Compose network).
- `BLUEBUBBLES_URL` must be reachable **from inside the container** — use a
  hostname/IP the container can resolve (e.g. the BlueBubbles host's LAN address or
  `host.docker.internal`), not `localhost`.

## License

MIT