matrix-channel

Matrix Channel for Claude Code

Chat with Claude Code from any Matrix client — Element, Element X, FluffyChat, or any other Matrix-compatible app.

This MCP server connects a Matrix bot to your Claude Code session. When someone messages the bot, Claude receives it and can reply, react, edit messages, fetch history, and download attachments — all through Matrix.

Features:

• End-to-end encryption (E2EE) with automatic key management
• Access control with pairing codes, allowlists, and per-room policies
• Works in DMs and group rooms (with optional @mention triggering)
• File attachments (send and receive)
• Device verification (SAS emoji) and local trust
• Configurable runtime (Bun, npx tsx, Deno)

Prerequisites

• Bun (default) or another TypeScript runtime (see Alternative Runtimes)
• A Matrix homeserver you have access to (e.g. your own Synapse instance, or matrix.org)
• A dedicated Matrix account for the bot

End-to-End Encryption

E2EE is supported. The bot works in both encrypted and unencrypted rooms.

The crypto store (identity keys, Olm sessions, megolm room keys) is persisted to disk and restored on startup, so the bot keeps the same device identity across restarts. Devices for users in the allowlist are automatically locally trusted on startup — no manual trust step is needed.

By default, the bot encrypts for all devices in the room and accepts messages from unverified devices. To require device verification (stricter security), set "requireVerifiedDevice": true in access.json.

To verify the bot's device (optional, or required if requireVerifiedDevice is enabled):

• From Element: Go to the bot user's profile → Sessions → Click the bot's device → Verify
• From the terminal: Run /matrix:verify to interactively verify devices
• To locally trust all devices for a user without SAS: use the verify_device tool with action trust

Quick Setup

1. Create a Matrix account for the bot

Register a new account on your homeserver for the bot. If your homeserver has open registration disabled (most do), you'll need admin access.

With Synapse admin access (SSH to your server):

docker exec synapse register_new_matrix_user \
  -u mybotname \
  -p 'a-strong-password-here' \
  --no-admin \
  -c /data/homeserver.yaml \
  http://localhost:8008

With open registration enabled, use any Matrix client (Element, etc.) to register a new account.

2. Get the access token

Log in with the bot account to get an access token:

curl -X POST "https://your-homeserver/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  -d '{"type":"m.login.password","user":"mybotname","password":"a-strong-password-here"}'

The response includes access_token — save it, you'll need it in step 4.

3. Clone and install

git clone https://github.com/Bakhtarian/Claude-Matrix-Channel.git
cd Claude-Matrix-Channel
bun install

4. Install the Claude Code plugin

Register the marketplace and install the plugin to get the /matrix:access, /matrix:configure, and /matrix:verify skills:

/plugin marketplace add Bakhtarian/Claude-Matrix-Channel
/plugin install matrix@matrix-channel

5. Configure credentials

Create the credentials file:

mkdir -p ~/.claude/channels/matrix
cat > ~/.claude/channels/matrix/.env << 'EOF'
MATRIX_HOMESERVER_URL=https://your-homeserver
MATRIX_ACCESS_TOKEN=syt_your_access_token_here
EOF
chmod 600 ~/.claude/channels/matrix/.env

Replace https://your-homeserver and the access token with your actual values from steps 1-2.

6. Create a room and invite the bot

Create a room and invite the bot. Both encrypted and unencrypted rooms work. For encrypted rooms, you'll need to verify the bot's device after setup (see "End-to-End Encryption" above).

Using the Matrix API (replace the homeserver URL and your access token):

# Create the room (using YOUR personal access token, not the bot's)
curl -X POST "https://your-homeserver/_matrix/client/v3/createRoom" \
  -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claude Bot",
    "preset": "public_chat",
    "visibility": "private"
  }'

This returns a room_id (e.g. !abc123:your-homeserver). Then invite the bot:

curl -X POST "https://your-homeserver/_matrix/client/v3/rooms/ROOM_ID/invite" \
  -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"@mybotname:your-homeserver"}'

The bot will auto-join when the server starts. You can also create the room using Element (make sure to disable encryption) and invite the bot from the UI.