matrix-channel-mcp

A small MCP server that bridges one Matrix room to Claude Code's claude/channel feature. Send a message from Matrix (e.g. Element) and it reaches your Claude Code session; Claude answers back into the room. It's a way to talk to a running Claude Code session from your chat app.

Matrix room  ⇄  server.ts (MCP)  ⇄  Claude Code
 (a human)                          (your session)

Requirements

• Bun

• Docker + Docker Compose (only for the bundled local Matrix homeserver — skip if you already have one)

Related MCP server: Herald

Quick start

1. Install dependencies

bun install

2. Start a Matrix homeserver

The repo ships a ready-to-run local stack:

docker compose up -d

This starts:

• continuwuity — a Matrix homeserver on http://localhost:8008 (open registration, local dev only)

• element-web — a Matrix web client on http://localhost:8080

3. Create a bot account and a room

Open http://localhost:8080, register an account for the bot (e.g. claude), create a room, and note two things:

• the access token — Element → Settings → Help & About → Access Token

• the room ID (looks like !abcd…:localhost) — room Settings → Advanced → Internal room ID

Make sure the bot account is a member of the room.

4. Configure

The server reads Matrix credentials from environment variables:

Quick check that it starts:

MATRIX_ACCESS_TOKEN=… MATRIX_ROOM_ID='!…' bun server.ts

5. Wire it into Claude Code

.mcp.json already registers this project as the matrix MCP server. Add the credentials to its env block so Claude Code passes them to the server:

{
  "mcpServers": {
    "matrix": {
      "command": "bun",
      "args": ["server.ts"],
      "env": {
        "MATRIX_ACCESS_TOKEN": "…",
        "MATRIX_ROOM_ID": "!…"
      }
    }
  }
}

Restart / reconnect the MCP server in Claude Code (/mcp). Now messages posted in the Matrix room show up in your Claude Code session, and Claude replies back into the room.

Prefer to keep the token out of a committed file? Put the same env block in your global .claude/settings.local.json instead.

Transports

Runs over stdio by default (what Claude Code uses). It can also serve over HTTP:

bun server.ts --transport http --port 3000
bun server.ts --help          # all options

Development

bun run typecheck   # tsc --noEmit
bun run lint        # eslint      (lint:fix to autofix)
bun run format      # prettier    (format:check to verify)

See CLAUDE.md for the internal architecture and a few sharp edges (why the transport connects before sync, how logging is routed, and the zod version pin).