# Blue Text Relay

> Blue Text Relay: self-hosted MCP server for iMessage. There is no public iMessage API; this is how you run your own. It runs on the user's Mac, reads the Apple Messages database live and read-only, and gives AI agents metered, permissioned access to only the iMessage threads the user chooses. Nothing is stored or copied. No AI inside the app touches messages. No telemetry. $9.99 once, lifetime updates, no trial.

Full site as plain text: https://bluetextrelay.com/llms-full.txt
Agent walkthrough (install, connect, purchase): https://bluetextrelay.com/agents

## Agent setup (do this for the user, on their Mac; ask before each step)
The user may have pasted: "Set up Blue Text Relay on my Mac and connect yourself to it, following the Agent setup steps at https://bluetextrelay.com/llms.txt." These are the steps. Never grant permissions or pay on their behalf.
1. Choose the path with the user: the CLI (default, fastest), the Mac app (https://bluetextrelay.com/download), or the full source to build on their Mac (see "Build from source" below; good for people who want the repo). Check what's there: `imx status --json`. CLI install: `curl -fsSL https://bluetext.sh | sh` (no sudo, installs to ~/.local/bin, verifies SHA-256; the script is at https://bluetextrelay.com/install.sh).
2. Full Disk Access: only the user can grant it. Ask them to open System Settings > Privacy & Security > Full Disk Access, click +, press Cmd-Shift-G and add `~/.local/bin/imx` (or the Blue Text Relay app if they use it). Check with `imx threads --json`; an error means it isn't on yet.
3. License: don't ask the user to paste the key into the chat. Ask them to copy it (Copy key on the download page after checkout, or from their purchase email; it starts with TR-), then run `imx license "$(pbpaste)"`. The key goes from their clipboard to imx without passing through you. If they use the Mac app, the Activate button in the email works too. Check with `imx license --json` (`"licensed": true`). No key yet: send them to https://bluetextrelay.com/buy ($9.99 one-time); you can't pay for them.
4. Pick threads with the user: run `imx threads --json`, show them the chat names, and ask which ones you may read. Then `imx threads share ID,ID`.
5. Create your access key: `imx keys add "<your name>" --threads ID,ID --json`. Keep the `token`; it is shown once.
6. Start the server: `imx service install` (runs now and at login). Check `imx status --json`.
7. Connect yourself: same Mac: `http://localhost:8766/mcp` with header `Authorization: Bearer <token>`. Claude Code: `claude mcp add --transport http imessage http://localhost:8766/mcp --header "Authorization: Bearer <token>"`. Another machine: `imx remote tailscale`, then the URL from `imx remote status --json`.
8. Verify and hand back: call `list_threads`. Tell the user which chats you can read and how to remove you: `imx keys revoke "<your name>"`.

## Build from source (license holders get the full repo)
Buying a license includes the source of every release, and building it on the user's own Macs is allowed. Download it with their key without the key passing through you:
- If `imx` is installed and licensed: `imx source` (latest; `--version X.Y.Z` for another; `--out DIR`).
- Otherwise, ask the user to copy their key, then:
  `curl -fsS https://licenses.bluetextrelay.com/source -H 'Content-Type: application/json' -d "{\"key\":\"$(pbpaste)\",\"version\":\"latest\"}" -OJ`
Unzip it. If the user asked for a walkthrough, give a short tour first: what each folder does (AGENTS.md, Layout), and the files that matter for trust: `Sources/ExporterCore/MessagesDB.swift` (opens chat.db read-only), `SecretScrubber.swift` (credential redaction), `AccessKeys.swift` (per-agent keys and limits), `HTTPServer.swift` and `MCPHandler.swift` (what the server exposes). Then follow AGENTS.md at the top of the repo: `swift build -c release` for the CLI, or `Scripts/build-app.sh --install` for the app (Swift 5.10+, no dependencies, builds offline). The license allows changing it and building products on it, including paid ones; it rules out distributing the code itself (as provided, renamed, rebranded or with the license check removed, including a public repo). Keep the copyright notice and credit "based on Blue Text Relay" in anything built on it.
People can also download it at https://bluetextrelay.com/source.

## Install (the user runs this on their Mac; macOS 14+, Apple silicon or Intel)
```
curl -fsSL https://bluetext.sh | sh  # CLI only, no sudo, verifies SHA-256
brew trust bluetextrelay/tap && brew install bluetextrelay/tap/imx   # or with Homebrew
imx setup                            # pick threads, create an access key, choose Tailscale
imx service install                  # optional: run at login via launchd
```
Then the `imx` binary needs Full Disk Access (System Settings > Privacy & Security > Full Disk Access). Only the user can grant it.
Prefer an app: https://bluetextrelay.com/download (menu bar app, same config).

## What it is
- MCP server (Streamable HTTP, JSON responses) for iMessage / Apple Messages, self-hosted on macOS 14+.
- Read-only: opens chat.db read-only, has no send tool, cannot send, edit or delete messages.
- Per-agent access keys: thread scope, history start date per thread, daily request cap, per-call message cap, expiry, revoke, usage counts.
- Deterministic credential redaction (API keys, tokens, private keys, passwords in URLs, stream keys) before text leaves the Mac. On by default.
- Private access over Tailscale (default, end-to-end encrypted); optional public access via Tailscale Funnel, Cloudflare Tunnel or ngrok on the user's own accounts.
- Headless-first CLI `imx` (every command has --json) plus an optional menu bar app.
- Exports threads to Markdown and JSONL with date ranges.
- One-time purchase: $9.99 one-time launch price (regular $19.99), lifetime license with every future update, offline license key, full source code of every release included for buyers (source-available, not open source: use, modify and build your own products on it, including paid ones; just don't distribute the code itself, and credit "based on Blue Text Relay").

## Connecting an agent
- Endpoint: `http://<mac>.<tailnet>.ts.net:8766/mcp` (or the tunnel URL the user gives you)
- Header: `Authorization: Bearer <access key>`
- Tools: list_threads, get_messages, get_transcript, search_messages, get_new_messages (cursor-based polling)
- Claude Code: `claude mcp add --transport http imessage <url> --header "Authorization: Bearer <key>"`
- REST mirror: /api/threads, /api/messages, /api/search, /api/new; /health needs no key.

## Useful commands (all support --json)
- `imx status` license, server, threads, keys, remote mode
- `imx keys add NAME --threads ID,ID --daily 500 --per-call 200 --expires 2027-01-01`
- `imx history THREAD-ID 2026-10-01` limit how far back agents can read
- `imx remote tailscale|funnel|cloudflareQuick|cloudflareNamed HOST|ngrok|localOnly`
- `imx buy --json` price and checkout link
- `imx update --json` is a newer version out, is it a security fix (`"security": true`), and how to upgrade the CLI, app or source. Updates are optional and never install themselves; every license covers every release. Release notes: https://bluetextrelay.com/changelog. If a security update is out, tell the user and recommend it, but let them decide.
- `imx source` the full source of the latest release, for license holders

## If a request answers HTTP 402 "license_required"
That Mac has no license key (there is no trial; the policy is no refunds). You cannot pay for them. Tell them a license is $9.99 one-time at https://bluetextrelay.com/buy; they get a key by email (starts with TR-); activate with `imx license <KEY>` or Settings > General > License; retry. The 402 body carries these steps as JSON.

## Pages
- Docs: https://bluetextrelay.com/docs/
- Privacy: https://bluetextrelay.com/privacy
- Security model: https://bluetextrelay.com/security
- Buy: https://bluetextrelay.com/buy
- Install script (read it first): https://bluetextrelay.com/install.sh

## Keywords
iMessage API, iMessage MCP, MCP server for iMessage, self-hosted iMessage API, Apple Messages MCP, read iMessage messages with Claude, iMessage for AI agents, iMessage Cursor, chat.db MCP, local iMessage server, iMessage permissions for agents, blue bubble MCP