convez.ai
MCP ServerIntegração & APIsIntermediário
TadMSTR

Matrix MCP Server

TadMSTR/matrix-mcp

Comunique agentes Claude via Matrix/Synapse com MCP nativo

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP em Python que conecta Claude a um homeserver Matrix (Synapse), permitindo que agentes enviem mensagens, compartilhem artefatos e coordenem atividades em salas dedicadas. Integra-se nativamente ao ecossistema de agentes Claude com suporte a arquivos, markdown renderizado e validação de segurança.

Instalação

$npx convez-ai TadMSTR/matrix-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 dias
Versão
v0.3.0
Issues abertas
0
Contribuidores
3

Casos de uso

  • Coordenação entre múltiplos agentes Claude em salas temáticas (dev, security, writer, etc.)
  • Alertas e notificações do sistema através de canais Matrix dedicados
  • Compartilhamento de artefatos (documentos, relatórios) com suporte a markdown e anexos

Veredito

Solução especializada para orquestração de agentes Claude via Matrix. Bem arquitetada com validações de segurança rigorosas (bind local, allowlist de paths, limite de mensagens) e suporte a multi-room. Recomendado para equipes que já usam Synapse e precisam de comunicação estruturada entre agentes.

README

A tradução para o português deste README ainda está na fila.

matrix-mcp

FastMCP server providing Matrix homeserver communication tools for forge agent sessions.

flowchart LR
    subgraph session["Claude Code session"]
        T["send_matrix_message\npost_artifact\nget_matrix_messages\nlist_matrix_rooms"]
    end

    MCP["matrix-mcp\n127.0.0.1:8487"]

    subgraph syn["Synapse homeserver"]
        CA["client API"]
        MR["media repo"]
    end

    ROOMS["agent rooms\n#writer · #dev · #security\n#announcements · …"]
    EW["Element Web\noperator"]

    T -->|HTTP| MCP
    MCP -->|text / markdown| CA
    MCP -->|"file > 50 KB"| MR
    CA --> ROOMS
    MR --> ROOMS
    ROOMS --> EW

Tools

ToolDescription
send_matrix_messageSend a message to a named agent room
get_matrix_messagesFetch recent messages from a room
list_matrix_roomsList all agent rooms with IDs
post_artifactPost a file's contents to a room (markdown rendered as HTML; >50KB uploaded as attachment)

Room names are short names (dev, task-queue, approvals, etc.) — no # or ! prefix needed.

Rooms

Short nameEnv varPurpose
sysadminMATRIX_ROOM_SYSADMINSysadmin agent activity
researchMATRIX_ROOM_RESEARCHResearch agent activity
developerMATRIX_ROOM_DEVDeveloper agent activity
securityMATRIX_ROOM_SECURITYSecurity audit findings
writerMATRIX_ROOM_WRITERWriter agent activity
alertsMATRIX_ROOM_ALERTSSystem alerts and notifications
agentsMATRIX_ROOM_AGENTSCross-agent coordination
announcementsMATRIX_ROOM_ANNOUNCEMENTSSystem-wide announcements
planeMATRIX_ROOM_PLANEPlane ticket feed notifications

Setup

cd ~/repos/personal/matrix-mcp
python3 -m venv venv
venv/bin/pip install -r requirements.txt

Credentials are loaded from ~/.claude-secrets/matrix.env (or the path in ENV_FILE). Required vars:

MATRIX_HOMESERVER_URL=https://matrix.example.com
MATRIX_BOT_USER_ID=@bot:example.com
MATRIX_ACCESS_TOKEN=<bot token>
MATRIX_ROOM_SYSADMIN=!...:example.com
MATRIX_ROOM_RESEARCH=!...:example.com
MATRIX_ROOM_DEV=!...:example.com
MATRIX_ROOM_SECURITY=!...:example.com
MATRIX_ROOM_WRITER=!...:example.com
MATRIX_ROOM_ALERTS=!...:example.com
MATRIX_ROOM_AGENTS=!...:example.com
MATRIX_ROOM_ANNOUNCEMENTS=!...:example.com
MATRIX_ROOM_PLANE=!...:example.com

All room vars are validated at startup — the server exits immediately if any are missing or empty.

Running

PM2 (production)

pm2 start ~/repos/personal/matrix-mcp/ecosystem.config.json
pm2 save

Manual

cd ~/repos/personal/matrix-mcp
ENV_FILE=~/.claude-secrets/matrix.env venv/bin/fastmcp run server.py --transport http --host 127.0.0.1 --port 8487

Claude Project Integration

Add to ~/.claude.json global MCP servers:

{
  "mcpServers": {
    "matrix": {
      "type": "http",
      "url": "http://127.0.0.1:8487/mcp"
    }
  }
}

Security

  • Binds to 127.0.0.1 only — not reachable from LAN
  • post_artifact validates paths against an allowlist before any filesystem access
  • get_matrix_messages limit is capped at 100
  • Unknown room names raise an error — never treated as literal room IDs
  • Credentials asserted at startup; server exits with error if any are missing
Ver o original no GitHub

Bom para

Relacionados