dendrite-admin-mcp

An MCP (Model Context Protocol) server that exposes Dendrite's admin API as tools, so an LLM agent can administer a Dendrite Matrix homeserver: manage users, evacuate/purge rooms, send server notices, manage registration tokens, and more.

Setup

npm install
cp .env.example .env   # fill in DENDRITE_BASE_URL and DENDRITE_ADMIN_TOKEN
npm run build

Configuration

Related MCP server: litellm-mcp

Transports

This server supports two MCP transports, selected via MCP_TRANSPORT:

• stdio (default) — for a client that spawns this process directly (e.g. a local Claude Code / editor MCP config). No network exposure.

• http — runs a stateless Streamable HTTP MCP server on MCP_HTTP_HOST:MCP_HTTP_PORT (default 0.0.0.0:3939), for remote clients over LAN/Tailscale. Requires MCP_AUTH_TOKEN; every request to /mcp must send Authorization: Bearer <token>. Generate one with openssl rand -hex 32.

Running

npm run build && npm start

For local development with auto-reload:

npm run dev

To poke at the tools interactively (stdio transport):

npm run inspector

Running with Docker

cp .env.example .env   # fill in DENDRITE_BASE_URL, DENDRITE_ADMIN_TOKEN,
                         # set MCP_TRANSPORT=http and MCP_AUTH_TOKEN
docker compose up -d --build

This builds the image, starts the container with restart: unless-stopped, and publishes port 3939. A /healthz endpoint (no auth required) backs the container healthcheck.

Tools

purge_room and evacuate_* are irreversible/disruptive — see CLAUDE.md for guidance on when an agent should confirm before calling them.

Connecting a remote client (HTTP transport)

Once deployed with MCP_TRANSPORT=http, point a client at http://<host>:3939/mcp with an Authorization: Bearer <MCP_AUTH_TOKEN> header. <host> can be a LAN IP or a Tailscale IP/MagicDNS name — whichever the client can reach.

Claude Code:

claude mcp add --transport http dendrite-admin --scope user \
  http://<host>:3939/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

opencode (~/.config/opencode/opencode.jsonc for a user-wide server):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "dendrite-admin": {
      "type": "remote",
      "url": "http://<host>:3939/mcp",
      "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
    }
  }
}

Codex CLI (~/.codex/config.toml):

[mcp_servers.dendrite-admin]
url = "http://<host>:3939/mcp"
bearer_token_env_var = "DENDRITE_ADMIN_MCP_TOKEN"

bearer_token_env_var names an environment variable Codex reads at startup — export it in your shell profile, e.g. export DENDRITE_ADMIN_MCP_TOKEN=<MCP_AUTH_TOKEN>.