Skip to main content
Glama
deenesjakoruzh
sagelabs-dev

matrix-mcp-server

by sagelabs-dev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

@guan-tends/matrix-mcp-server

npm version License: MIT Node.js Version

Matrix 채팅 작업을 호출 가능한 도구로 노출하는 독립형 MCP(Model Context Protocol) 도구 서버입니다. 모든 MCP 호환 클라이언트 — AI 에이전트, 자동화 파이프라인, 개발자 도구 — 는 이러한 도구를 사용하여 메시지 전송, 방 관리, 이름 확인, Matrix 프로토콜 상호작용을 수행할 수 있습니다.

@vector-im/matrix-bot-sdk 기반으로 구축되었으며 완전한 E2EE(종단간 암호화)를 지원합니다.

기능

  • 15개의 MCP 도구 — 메시징, 방 관리, 사용자 관리, 지능형 ID 확인

  • E2EE 지원 — Rust 암호화 백엔드를 통한 완전한 Megolm 암호화

  • 사람 친화적인 이름 확인 — 불투명한 ID 대신 이름으로 방과 사용자 참조

  • 별칭 시스템 — 서버에 사용자 정의 단축키 학습 가능 (예: "eng" → "!abc123:matrix.org")

  • 독립형 HTTP 서버 — 독립적으로 실행되며, HTTP를 통해 모든 MCP 클라이언트 연결 가능

  • 크론 없음, 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

Matrix 자격 증명으로 config.json5을 편집하세요:

{
  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에서 수신 대기하며 HTTP를 통해 MCP 프로토콜 요청을 수락합니다.

3. MCP 클라이언트 연결

모든 MCP 호환 클라이언트를 서버에 연결하세요:

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

또는 다중 서버 도구 구성을 위해 @guan-tends/mcp-ai 애그리게이터와 함께 사용하세요.

구성

파일 기반

config.json5을 편집하세요 (모든 옵션은 config.example.json5 참조).

환경 변수

모든 구성 값은 환경 변수로 설정할 수 있습니다 (최우선 순위):

변수

구성 키

MATRIX_MCP_HOMESERVER_URL

homeserverUrl

MATRIX_MCP_ACCESS_TOKEN

accessToken

MATRIX_MCP_PORT

port

MATRIX_MCP_HOST

host

MATRIX_MCP_SERVER_NAME

serverName

MATRIX_MCP_STORE_PATH

storePath

MATRIX_MCP_CRYPTO_PATH

cryptoPath

도구 (15개)

메시징

도구

설명

send_message

방에 텍스트 전송 (ID 또는 확인된 이름으로)

send_html_message

HTML 형식 메시지 전송

send_reaction

메시지에 이모지로 반응

send_dm

직접 메시지 전송 (필요시 암호화된 DM 생성)

방 관리

도구

설명

join_room

ID 또는 별칭으로 방 참여

leave_room

방 나가기

get_joined_rooms

참여 중인 모든 방 나열

get_room_messages

방에서 최근 메시지 가져오기

사용자 관리

도구

설명

get_presence

사용자의 현재 상태 가져오기

invite_user

사용자를 방에 초대

kick_user

사용자를 방에서 추방

ID 확인

도구

설명

set_room_alias

서버에 방 별칭 학습 (예: "eng" → "!abc:matrix.org")

set_user_alias

서버에 사용자 별칭 학습 (예: "alice" → "@alice:matrix.org")

resolve_room

방 이름을 신뢰 점수와 함께 Matrix ID로 확인

resolve_user

사용자 이름을 신뢰 점수와 함께 Matrix 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
            └──────────────────┘

구성 루트 IoC: index.js가 모든 의존성을 연결합니다. 어떤 모듈도 다른 모듈의 의존성을 가져오지 않습니다. 각 모듈은 독립적으로 테스트 가능합니다.

설계 결정

  1. 구성 루트 IoC — index.js가 모든 의존성을 연결합니다. 모듈 간 교차 가져오기가 없습니다.

  2. 최소 AliasStore — 방/사용자 별칭 관리에 필요한 메서드는 4개뿐입니다.

  3. 간단한 JSON 영속성 — persist.js가 로드/저장을 처리합니다. 데이터 파일 2개.

  4. withErrorHandling 래퍼 — 모든 도구에서 반복되는 try/catch를 DRY로 처리합니다.

  5. 크론 없음, LLM 없음, 봇 없음 — 순수 MCP 도구 서버. 에이전트가 자체 일정을 관리합니다.

테스트

# All tests (unit + E2E)
npm test

# Watch mode
npm run test:watch

# With coverage
npm run test:coverage

65개 테스트 — 6개 파일 (단위 5개, E2E 1개).

프로젝트 구조

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • ottoauthMCP

    Clamepending
    F
    license
    A
    quality
    D
    maintenance
    Standalone MCP server that proxies tool calls to Ottoauth HTTP endpoints, enabling account creation and dynamic service interaction.
    7
    -

  • rocketchat-mcp

    SufiSR
    F
    license
    Not graded
    quality
    D
    maintenance
    MCP server for Rocket.Chat, enabling AI agents to interact with Rocket.Chat workspaces via tools like listing users, sending messages, and managing channels.
    2
    -

  • matrix-mcp

    cosmic-fire-eng
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for Matrix that lets Claude list rooms, search/read messages, send messages and files, react, create rooms, and invite users, with multi-homeserver support and safe-by-default writes; no end-to-end encryption.
    MIT