XMPP Channel for Claude Code

Connect an XMPP account to your Claude Code session. Message Claude from any XMPP client on your phone (Monal, Conversations, ChatSecure, Gajim, etc.) over the federated XMPP network.

The MCP server logs into XMPP as a bot and provides tools to Claude to reply or edit messages. When you message the bot, the server forwards the message to your Claude Code session.

Why XMPP?

• No phone number required (unlike Telegram)
• Federated — pick any server, switch anytime
• OMEMO end-to-end encryption (client-side)
• Works on older devices (iPhone 6s, etc.)
• Unlimited simultaneous clients

Prerequisites

• Bun — install with curl -fsSL https://bun.sh/install | bash
• An XMPP account for the bot (register on any public server: yax.im, xmpp.jp, etc.)

Quick Setup

1. Clone and install

git clone https://github.com/nickolanack/xmpp-channel.git
cd xmpp-channel
bun install

2. Register the MCP server

Add to your project's .mcp.json (or ~/.claude/.mcp.json for global):

{
  "mcpServers": {
    "xmpp": {
      "command": "bun",
      "args": ["run", "/path/to/xmpp-channel/server.ts"]
    }
  }
}

3. Configure credentials

Create ~/.claude/channels/xmpp/.env:

XMPP_JID=yourbot@server.com
XMPP_PASSWORD=your-password

If your server requires direct TLS (e.g. yax.im under Bun):

XMPP_JID=yourbot@yax.im
XMPP_PASSWORD=your-password
XMPP_SERVICE=xmpps://xmpp.yaxim.org:443

The .env file is automatically chmod 600 on first read.

4. Configure the allowlist

Create ~/.claude/channels/xmpp/access.json:

{
  "policy": "allowlist",
  "allowFrom": ["you@your-xmpp-server.com"]
}

Only JIDs in allowFrom can message the bot. All others are silently dropped.

5. Launch

claude --dangerously-load-development-channels server:xmpp

Message the bot's JID from your XMPP client — the message reaches Claude.

Tools exposed to Claude

Tool	Purpose
reply	Send a message to an XMPP JID. Auto-chunks at 4000 chars.
edit_message	Correct a previously sent message (XEP-0308).

Permission relay

When Claude needs to run a tool that requires approval, you get a message like:

Permission: Bash
Run shell command: npm install
Reply: y abcde / n abcde
Reply: more abcde for full details

Reply with y abcde to allow or n abcde to deny (the 5-character code is required).

Access control

Managed via ~/.claude/channels/xmpp/access.json. The server re-reads this file on every inbound message — changes take effect without restart.

{
  "policy": "allowlist",
  "allowFrom": ["alice@server.com", "bob@server.com"],
  "ackMessage": "",
  "textChunkLimit": 4000,
  "chunkMode": "newline"
}

Field	Description
policy	allowlist (default) or disabled
allowFrom	Array of bare JIDs allowed to message the bot
ackMessage	Optional text sent on receipt (e.g. "received"). Empty = disabled.
textChunkLimit	Max chars per outbound message before splitting (default: 4000)
chunkMode	newline (paragraph-aware) or length (hard cut)

Skills

If installed as a plugin, two skills are available:

Skill	Purpose
/xmpp:configure	Guided first-time setup (writes .env + access.json)
/xmpp:access	Manage allowlist (allow/remove JIDs, set policy, configure delivery)

Connection notes

STARTTLS vs direct TLS

@xmpp/client under Bun may hang during STARTTLS negotiation on some servers. If your bot gets stuck at "opening" status, switch to direct TLS:

1. Find your server's SRV records: dig +short SRV _xmpps-client._tcp.yourserver.com
2. Set XMPP_SERVICE=xmpps://host:port in .env

Example for yax.im:

XMPP_SERVICE=xmpps://xmpp.yaxim.org:443

Multiple Claude Code sessions

Each session binds with a unique XMPP resource (claudecode-<pid>). Multiple sessions can connect with the same JID, but message routing depends on server configuration.

Security

• Allowlist enforced on both inbound (gate) and outbound (reply/edit can only target allowlisted JIDs)
• Input sanitization strips <>[] from inbound messages to prevent channel tag injection
• State protection prevents Claude from exfiltrating .env or access.json via file operations
• Prompt injection defense in Claude's system instructions — refuses to modify access when asked via channel messages
• Credential isolation — .env is chmod 600, never committed to git

License

MIT