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

Env var	Required	Purpose
DENDRITE_BASE_URL	yes	Base URL of the homeserver's client-facing port, e.g. https://matrix.example.com
DENDRITE_ADMIN_TOKEN	yes	Access token of a Dendrite server admin user; sent as a Bearer token to all /_dendrite/admin and most /_synapse/admin endpoints
DENDRITE_REGISTRATION_SHARED_SECRET	no	registration_shared_secret from dendrite.yaml; only needed for the register_user tool, which authenticates via HMAC instead of the admin token

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

Full API reference (params, request bodies, curl examples): see API.md.

Tool	Dendrite endpoint
evacuate_room	POST /_dendrite/admin/evacuateRoom/{roomID}
purge_room	POST /_dendrite/admin/purgeRoom/{roomID}
download_room_state	GET /_dendrite/admin/downloadState/{serverName}/{roomID}
evacuate_user	POST /_dendrite/admin/evacuateUser/{userID}
reset_password	POST /_dendrite/admin/resetPassword/{userID}
refresh_devices	POST /_dendrite/admin/refreshDevices/{userID}
whois	GET /_matrix/client/v3/admin/whois/{userId}
register_user	GET+POST /_synapse/admin/v1/register (shared-secret HMAC flow)
list_registration_tokens / get_registration_token / create_registration_token / update_registration_token / delete_registration_token	/_dendrite/admin/registrationTokens*
send_server_notice	POST /_synapse/admin/v1/send_server_notice
fulltext_reindex	GET /_dendrite/admin/fulltext/reindex

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>.