@guan-tends/matrix-mcp-server

Автономный сервер инструментов MCP (Model Context Protocol), который предоставляет операции чата Matrix в виде вызываемых инструментов. Любой MCP-совместимый клиент — AI-агенты, конвейеры автоматизации, инструменты разработчика — может использовать эти инструменты для отправки сообщений, управления комнатами, разрешения имён и взаимодействия с протоколом Matrix.

Создан на базе @vector-im/matrix-bot-sdk с полной поддержкой E2EE (сквозного шифрования).

Возможности

• 15 MCP-инструментов — обмен сообщениями, управление комнатами, управление пользователями и интеллектуальное разрешение ID

• Поддержка E2EE — полное шифрование Megolm через криптографический бэкенд на Rust

• Понятные человеку имена — обращайтесь к комнатам и пользователям по имени, а не по непрозрачным ID

• Система алиасов — научите сервер собственным сокращениям (например, "eng" → "!abc123:matrix.org")

• Автономный HTTP-сервер — работает независимо, подключайте любой MCP-клиент через HTTP

• Никакого cron, никакого LLM — чистый сервер инструментов. Планирование и интеллект живут в слое агента

Related MCP server: ottoauthMCP

Установка

npm install @guan-tends/matrix-mcp-server

Требования

• Node.js >= 22.0.0

• Учётная запись Matrix с токеном доступа

Быстрый старт

1. Клонируйте и настройте

git clone https://github.com/guan-tends/matrix-mcp-server.git
cd matrix-mcp-server
npm install
cp config.example.json5 config.json5

Отредактируйте config.json5, указав свои учётные данные Matrix:

{
  homeserverUrl: "https://matrix.org",
  accessToken: "syt_...",
  serverName: "matrix.org",
  port: 3456,
  host: "0.0.0.0",
  storePath: "./data/store.json",
  cryptoPath: "./data/crypto",
}

2. Запуск

npm start

Сервер слушает http://0.0.0.0:3456 и принимает запросы по протоколу MCP через HTTP.

3. Подключите свой MCP-клиент

Направьте любой MCP-совместимый клиент на сервер:

{
  "mcpServers": {
    "matrix": {
      "url": "http://localhost:3456"
    }
  }
}

Или используйте агрегатор @guan-tends/mcp-ai для композиции инструментов с нескольких серверов.

Конфигурация

На основе файла

Отредактируйте config.json5 (все опции см. в config.example.json5).

Переменные окружения

Все значения конфигурации можно задать через переменные окружения (наивысший приоритет):

Инструменты (15)

Обмен сообщениями

Управление комнатами

Управление пользователями

Разрешение ID

Стратегия разрешения имён

Резолвер использует гибридный подход с оценкой уверенности:

1. Алиасы пользователей (уверенность: 1.0) — заданные пользователем сопоставления

2. Точное совпадение (уверенность: 0.9) — точное отображаемое имя или канонический алиас

3. Частичное совпадение (уверенность: 0.7) — частичное совпадение имени

4. Неоднозначность (уверенность: 0.5) — несколько совпадений, возвращаются кандидаты

Архитектура

                    ┌─────────────────────────┐
                    │      index.js            │
                    │   (composition root)     │
                    └──────────┬──────────────┘
                               │ wires
              ┌────────────────┼────────────────┐
              ▼                ▼                 ▼
     ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
     │ MatrixClient │  │  AliasStore  │  │ McpDataStore │
     │ (bot-sdk)    │  │ (aliases)    │  │ (DM cache)   │
     └──────┬───────┘  └──────┬───────┘  └──────┬───────┘
            │                 │                  │
            └────────┬────────┘                  │
                     ▼                           │
            ┌──────────────────┐                 │
            │ MatrixIdResolver  │◄────────────────┘
            └────────┬─────────┘
                     │
                     ▼
            ┌──────────────────┐
            │   mcp-server.js   │── MCP SDK SimpleServer
            │   (15 tools)      │── HTTP transport
            └──────────────────┘

Composition-Root IoC: index.js связывает все зависимости. Ни один модуль не импортирует зависимости другого. Каждый модуль можно тестировать независимо.

Проектные решения

1. Composition-Root IoC — index.js связывает все зависимости. Модули не импортируют друг друга.

2. Минимальный AliasStore — для управления алиасами комнат и пользователей нужно всего 4 метода.

3. Простое JSON-хранилище — persist.js отвечает за загрузку и сохранение. Два файла данных.

4. Обёртка withErrorHandling — устраняет повторяющиеся try/catch в каждом инструменте.

5. Никакого cron, никакого LLM, никакого бота — чистый MCP-сервер инструментов. Агенты сами управляют своим планированием.

Тестирование

# All tests (unit + E2E)
npm test

# Watch mode
npm run test:watch

# With coverage
npm run test:coverage

65 тестов в 6 файлах (5 модульных, 1 E2E).

Структура проекта

src/
├── index.js              — Composition root: config → Matrix client → wire → start
├── mcp-server.js          — 15 MCP tools + helpers (withErrorHandling, resolveRoomInput, etc.)
├── matrix-id-resolver.js  — Room/user name → Matrix ID resolution
├── alias-store.js         — Minimal per-user alias storage
├── mcp-data-store.js      — DM room ID cache
└── persist.js             — Simple JSON load/save utility

__tests__/
├── unit/                  — Unit tests (alias-store, mcp-data-store, resolver, mcp-server, persist)
├── e2e/                   — E2E test (full server start → MCP client → tool calls)
├── mocks/                 — Mock MatrixClient for testing
└── vitest.config.js

Спонсоры

Если этот проект полезен для вас, поддержите его развитие:

• GitHub Sponsors

• Solana: Eu8wQcW68TKMs1a6eqzZu8znzU52QLqQugAMG8uCD6y6

• EVM (Ethereum / Base / Arbitrum / Optimism / Polygon): 0x2733ff7c865C56d565a99BE1DC11B81cc76850A5

• XRP Ledger: r4X6e7McAQj7e8vBCeued1RYu4mCJrREDG

Лицензия

MIT © 2026 Guan