MCP integration¶

chatwire exposes an MCP (Model Context Protocol) server that lets LLM clients — Claude, GPT, and any MCP-compatible agent — read conversations and send messages on your behalf.

What is MCP?¶

MCP is an open protocol for connecting LLM clients to external tools and data sources. chatwire implements an MCP server so you can say "reply to Alice's message with ..." in Claude Code or Claude Desktop, and it actually sends the iMessage from your Mac.

Install MCP support¶

MCP support is an optional extra — it's not installed by default:

pipx inject chatwire "chatwire[mcp]"
# or:
pip install "chatwire[mcp]"

Verify:

chatwire doctor
#   ✓ MCP package — installed

Start the MCP server¶

chatwire's MCP server uses stdio transport (stdin/stdout):

chatwire mcp

Configure this as a local MCP server in your LLM client.

Claude Code configuration¶

Add to ~/.claude/claude_desktop_config.json (or the equivalent MCP server config):

{
  "mcpServers": {
    "chatwire": {
      "command": "chatwire",
      "args": ["mcp"]
    }
  }
}

Claude Desktop configuration¶

Same format — add to the MCP servers section in Claude Desktop settings.

Other clients¶

Any MCP-compatible client that supports stdio transport will work. Point it at chatwire mcp.

Available tools¶

The MCP server exposes these tools to the LLM client:

Tool	Description
`list_conversations`	List recent conversations with sender names and timestamps
`get_messages`	Get messages in a conversation (by handle or group GUID)
`send_message`	Send an iMessage or SMS to a contact
`search_messages`	Search messages by text (full-text search)
`get_contact`	Look up a contact by handle or name
`list_whitelist`	List whitelisted contacts

Scopes and access control¶

MCP tool access is controlled by scopes. Configure which scopes are available in Settings → MCP:

Scope	Tools unlocked
`read`	`list_conversations`, `get_messages`, `search_messages`, `get_contact`, `list_whitelist`
`write`	`send_message`

The write scope lets the LLM send messages as you. Enable it only with clients you trust.

Confirmation flow: When write scope is enabled, chatwire can optionally prompt for confirmation before sending. Configure in Settings → MCP → Require confirmation for sends.

API keys for MCP¶

If your chatwire instance has a web UI password set, you'll need an API key for MCP:

Open Settings → Security → API Keys
Click Generate new key
Choose the scopes (read, write, or both)
Copy the key (format: cwk_<hex>)

Provide the key as a Bearer token when configuring the MCP client, or set it in the MCP server configuration:

{
  "mcpServers": {
    "chatwire": {
      "command": "chatwire",
      "args": ["mcp"],
      "env": {
        "CHATWIRE_API_KEY": "cwk_yourkeyhere"
      }
    }
  }
}

Security considerations¶

The write scope lets an LLM send messages as you. Only enable it with trusted clients and carefully-scoped agents.
MCP uses stdio transport — no network port is exposed. The LLM client launches chatwire mcp as a subprocess on the same machine.
Scopes are enforced — a client with only read scope cannot send messages, even if the LLM asks for it.
Rate limiting — MCP sends go through the same anti-spam fuse as web UI sends.

Troubleshooting¶

chatwire mcp fails with import error:

chatwire mcp: MCP support requires the 'mcp' package.
Install it with: pip install 'chatwire[mcp]'

Run pipx inject chatwire "chatwire[mcp]" and try again.

Tools don't appear in the LLM client: - Verify the MCP server config points to the right chatwire binary (which chatwire) - Start chatwire mcp manually and check for errors - Restart the LLM client after updating the config

Send tool is unauthorized: - Check that your API key has write scope - Or disable the web UI password (if on a trusted network) — no auth required then