matrix-agent-mcp

@northbound-run/matrix-agent-mcp is an MCP server that exposes 31 Matrix tools (send messages, list rooms, manage membership, upload media, and more) to any MCP-compatible host. It runs in stdio mode by default and can also serve a hosted HTTP endpoint for network access.

Connect from Claude Desktop

Prerequisites

Claude Desktop installed
A Matrix account with an access token, user ID, and homeserver URL
Bun installed

Add the server

Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) and add a matrix entry under mcpServers:

json

{
  "mcpServers": {
    "matrix": {
      "command": "bunx",
      "args": ["@northbound-run/matrix-agent-mcp"],
      "env": {
        "MATRIX_ACCESS_TOKEN": "your-access-token",
        "MATRIX_USER_ID": "@yourbot:matrix.org",
        "MATRIX_HOMESERVER_URL": "https://matrix.org"
      }
    }
  }
}

MATRIX_HOMESERVER_URL defaults to https://matrix.agentchannels.dev if omitted.

Quit and relaunch Claude Desktop. The Matrix tools (matrix_send, matrix_list_rooms, etc.) appear in the tool list on the next conversation.

Credentials file

If you prefer not to embed secrets in the config, pass a credentials file:

json

{
  "mcpServers": {
    "matrix": {
      "command": "bunx",
      "args": [
        "@northbound-run/matrix-agent-mcp",
        "--credentials",
        "/path/to/creds.json"
      ]
    }
  }
}

The file is a JSON object with accessToken, userId, and homeserverUrl. See the multi-account section for the array format.

Verify

Ask Claude: "List my Matrix rooms." Claude calls matrix_list_rooms and returns the rooms your account is joined to.

Connect from Cursor

Add the server

Open Cursor's MCP settings (Settings → MCP or the mcp.json config file) and add:

json

{
  "mcpServers": {
    "matrix": {
      "command": "bunx",
      "args": [
        "@northbound-run/matrix-agent-mcp",
        "--credentials",
        "/path/to/creds.json"
      ]
    }
  }
}

Using a credentials file keeps secrets out of the Cursor settings file. The file is a single JSON object:

json

{
  "accessToken": "your-access-token",
  "userId": "@yourbot:matrix.org",
  "homeserverUrl": "https://matrix.org"
}

Environment variables work the same way as Claude Desktop — use the env key instead.

After saving, restart the MCP servers (Cursor's "Restart MCP servers" command or restart the app). The Matrix tools appear in the tool panel.

Remote hosted server

If the MCP server is running in hosted mode on a remote machine:

json

{
  "mcpServers": {
    "matrix": {
      "url": "https://your-server.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-token"
      }
    }
  }
}

Hosted deployment

Hosted mode starts an HTTP server on 0.0.0.0:3100 and protects /mcp with Bearer token authentication. Use it for a single persistent server shared across multiple clients or deployed on a remote machine.

Start

bunx @northbound-run/matrix-agent-mcp \
  --hosted \
  --bearer-token your-secret-token \
  --credentials ./creds.json

Or with environment variables:

HOSTED_MODE=true \
MCP_BEARER_TOKEN=your-secret-token \
bunx @northbound-run/matrix-agent-mcp --credentials ./creds.json

Override the port with --port <n> or the PORT env var.

Verify

curl http://localhost:3100/health

/health is always unauthenticated:

json

{
  "status": "ok",
  "accounts": [
    { "userId": "@yourbot:matrix.org", "syncState": "running" }
  ]
}

Confirm the MCP endpoint requires authentication:

curl -I http://localhost:3100/mcp
# → 401 Unauthorized
 
curl -H "Authorization: Bearer your-secret-token" \
  -X POST http://localhost:3100/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
# → 200 with tool list

Hosted flags

Flag	Env var	Description	Default
`--hosted`	`HOSTED_MODE=true`	Enable hosted mode	`false`
`--bearer-token <token>`	`MCP_BEARER_TOKEN`	Required when hosted mode is on	—
`--port <n>`	`PORT`	HTTP port	`3100`
`--host <addr>`	—	Bind address	`0.0.0.0`

Behavior differences

All /mcp requests must include Authorization: Bearer <token>; unauthenticated requests return 401.
/health is always unauthenticated.
matrix_login is disabled in hosted mode. Credentials are managed externally via --credentials or environment variables.

Multi-account

A single MCP server can connect multiple Matrix accounts simultaneously. Tools accept an account parameter to route calls.

Credentials file (array)

json

[
  {
    "accessToken": "token_for_bot1",
    "userId": "@bot1:matrix.org",
    "homeserverUrl": "https://matrix.org"
  },
  {
    "accessToken": "token_for_bot2",
    "userId": "@bot2:matrix.org",
    "homeserverUrl": "https://matrix.org"
  }
]

bunx @northbound-run/matrix-agent-mcp --credentials ./creds.json

Both accounts sync immediately. matrix_list_rooms returns rooms from all accounts by default.

Target a specific account

Every tool accepts an optional account parameter (Matrix user ID). When omitted, the first account in the array is used.

json

{
  "tool": "matrix_send",
  "arguments": {
    "roomId": "!abc:matrix.org",
    "message": "Hello from bot2",
    "account": "@bot2:matrix.org"
  }
}