Matrix MCP Server: Interact With Homeserver

Overview

Matrix MCP Server is a lightweight adapter that exposes a simple API for programmatic interaction with a Matrix homeserver. It is designed to make common homeserver operations (sending messages, querying room state, managing users and rooms) accessible to other services and models via a single, predictable endpoint. This is useful when you want to integrate chat-enabled agents, automation scripts, or monitoring systems with Matrix without embedding Matrix client logic into every component.

The server acts as a thin gateway: it translates compact API calls into Matrix Client-Server API operations, handling authentication, rate-limiting considerations, and common error patterns. Developers can deploy it alongside application code or models to give automated systems controlled, auditable access to a Matrix installation.

Features

• REST API that abstracts common Matrix client-server operations
• Send messages to rooms or users (text, formatted bodies)
• Query room state and membership lists
• Create, join, invite, and manage rooms
• Manage users (ban, unban, kick) and fetch profile data
• Simple configuration via environment variables or YAML config
• Docker-friendly for quick deployment
• Lightweight and suitable for integration with bots, automations, or model-driven agents

Installation / Configuration

Clone and build from source (requires Go 1.18+):

git clone https://github.com/mjknowles/matrix-mcp-server.git
cd matrix-mcp-server
go build ./cmd/matrix-mcp-server
./matrix-mcp-server --config config.yaml

Run with Docker:

docker run -p 8080:8080 \
  -e MATRIX_HOMESERVER_URL=https://matrix.example.org \
  -e MATRIX_ACCESS_TOKEN=YOUR_ACCESS_TOKEN \
  -e LISTEN_ADDR=0.0.0.0:8080 \
  mjknowles/matrix-mcp-server:latest

Example docker-compose service:

version: "3.8"
services:
  matrix-mcp-server:
    image: mjknowles/matrix-mcp-server:latest
    ports:
      - "8080:8080"
    environment:
      MATRIX_HOMESERVER_URL: "https://matrix.example.org"
      MATRIX_ACCESS_TOKEN: "YOUR_ACCESS_TOKEN"
      LISTEN_ADDR: "0.0.0.0:8080"
      LOG_LEVEL: "info"

Example minimal YAML config (config.yaml):

server:
  listen_addr: ":8080"
matrix:
  homeserver_url: "https://matrix.example.org"
  access_token: "YOUR_ACCESS_TOKEN"
logging:
  level: "info"

Configuration environment variables and keys

Available Resources

The server exposes a RESTful API that wraps common Matrix operations. The exact paths may vary depending on release; below are representative endpoints and payload patterns used by clients integrating with the server.

• POST /api/v1/send_message
  • Send a message to a room or user.
  • Body example:

    {
      "room_id": "!abc123:example.org",
      "body": "Hello from MCP server",
      "msgtype": "m.text"
    }
    

• GET /api/v1/rooms/{room_id}/state
  • Retrieve full or filtered room state.
• GET /api/v1/rooms/{room_id}/members
  • List current members and their membership status.
• POST /api/v1/rooms/create
  • Create a new room with options (visibility, preset, invite list).
• POST /api/v1/rooms/{room_id}/invite
  • Invite a user to a room.
• POST /api/v1/rooms/{room_id}/ban
  • Ban a user from a room.
• GET /api/v1/users/{user_id}/profile
  • Fetch profile data (displayname, avatar).

Use curl to interact (example send message):

curl -X POST http://localhost:8080/api/v1/send_message \
  -H "Content-Type: application/json" \
  -d '{"room_id":"!room:example.org","body":"Hello world","msgtype":"m.text"}'

Authentication is usually handled by the server using the configured access token; the public API can be protected behind network controls or an API gateway.

Use Cases

• Automating notifications: send build or monitoring alerts into Matrix rooms from CI/CD pipelines or observability tools without embedding a Matrix client in each tool.
• Agent-driven chats: allow LLM-based assistants to read room context and post responses using a controlled, auditable API surface.
• Room management scripts: programmatically create rooms, add users, or enforce moderation rules from administrative tooling.
• Chat-to-service bridge: route incoming messages to other systems (ticketing, incident responders) and post back results.
• State inspection for tooling: fetch room membership, events, and state to generate reports or to drive business logic.

Tips for Developers

• Run the server with a dedicated bot account token scoped to the required privileges rather than a full admin token.
• Use network-level controls (VPC, firewall, API gateway) to restrict who can call the MCP server API.
• When integrating LLMs, treat actions that modify state (invite, ban, send) as gated operations — consider a review step or a strict allowlist.
• Monitor and log requests for auditability; configure log rotation and structured logging for downstream analysis.

Repository and issues: https://github.com/mjknowles/matrix-mcp-server — check the project README and issues for the latest endpoint details and updates.