mcp-twake-chat

Give your AI assistant secure access to Twake Chat, the Matrix messaging of the Twake.ai Digital Workplace, end-to-end encrypted rooms included.

What is it?

mcp-twake-chat is a Model Context Protocol (MCP) server. MCP is the open standard that lets AI assistants (Claude Desktop, Claude Code, Hermes Agent, Cursor, VS Code and many others) use external tools. This server exposes your chat to the assistant as 17 tools: rooms, messages, threads, unread messages, mentions, people, attachments, drafts and, when you allow it, sending.

It speaks the open Matrix Client-Server API through matrix-js-sdk and its Rust cryptography, so it reads end-to-end encrypted rooms like any Matrix client. It works with Twake Chat and with any Matrix homeserver (Synapse, Conduit…); the Twake-specific extras (company directory, recovery vault) come from the ToM server.

Related MCP server: mcp-server-mattermost

Part of Twake.ai

Twake.ai is the truly open source and sovereign Digital Workplace developed by LINAGORA: Twake Mail, Twake Calendar, Twake Drive, Twake Chat and Twake Visio with a single account, hosted in France or on your own infrastructure.

What it brings

• Catch up: "What did I miss on the chat since yesterday? Who mentioned me this week?"

• Summarise: "Summarise the project room for the last seven days."

• Find: "What did Alice say about the contract?", "Who is Bob Martin, and do we have a direct conversation?"

• Prepare answers safely: "Draft a reply to Alice": the draft lands in your private Drafts room, never in the conversation.

• Encrypted rooms: the server is a real Matrix device of your account, verified by cross-signing, and restores your key backup, so encrypted history is readable as in a new Twake Chat session.

• Sovereignty: the server runs next to your assistant and talks directly to your homeserver.

Features

17 MCP tools

⚠️ = acts in your name, visible to other people. Read tools carry readOnlyHint; create_draft is closed-world (openWorldHint: false); write tools carry openWorldHint and redact_message destructiveHint, so clients can ask for confirmation.

Highlights

• End-to-end encryption: Rust crypto (WASM) with a persistent store (IndexedDB emulated on SQLite, encrypted with a 32-byte key kept in a 0600 file). On first start the server unlocks your secret storage with your recovery key, imports the cross-signing keys, signs its own device and restores the server key backup; later starts use the local store only.

• Recovery key: read from the Twake ToM vault, where Twake Chat stores it (MATRIX_E2EE_RECOVERY=tom), or from a file (key), or not at all (off: only messages received after the first start are readable).

• One device, one process: the crypto store is locked by the running process. To share one device between several assistants, run the server once with the HTTP transport and point every client to it.

• Unread messages computed like a client: from your read receipt and read marker, because servers often return no notification count when push rules mute rooms.

• Mentions in encrypted rooms: found client-side (m.mentions, or your name in the text), which server-side notifications cannot see.

• Rooms by name: every tool accepts a room id, an alias, a DM partner id or a name, case and accents ignored; ambiguous names return the candidates.

• No password, no OAuth flow inside: short-lived access tokens come from an external broker you control.

Requirements

• Node.js >= 22

• A Matrix account on Twake Chat or any homeserver; key backup and secret storage set up for encrypted history

• An MCP client

Installation

git clone https://github.com/linagora/mcp-twake-chat.git
cd mcp-twake-chat
npm install
npm run build          # then: node build/index.js

Configuration

Authentication

The server never logs in by itself: it needs a Matrix access token and the device id it belongs to (the encryption store is bound to that device).

MATRIX_TOKEN_COMMAND prints {"access_token": "...", "expires_at": <epoch seconds>, "device_id": "...", "user_id": "..."} and is run again shortly before expiry. Your broker owns the login and the refresh-token rotation. With Synapse's SSO, a broker typically:

1. sends the user once to /_matrix/client/v3/login/sso/redirect/<idp>?redirectUrl=…;

2. exchanges the returned loginToken with POST /_matrix/client/v3/login (type: m.login.token, refresh_token: true, a clear initial_device_display_name);

3. refreshes with POST /_matrix/client/v3/refresh under a lock and prints the JSON above.

MATRIX_CREDENTIALS_FILE points to a file of KEY=VALUE lines (MATRIX_ACCESS_TOKEN=…, MATRIX_DEVICE_ID=…) to keep secrets out of the client configuration.

Other options

Check a configuration with node build/index.js check: it connects, prints the account, device, encryption state and room counts, and exits.

Use it with your assistant

Hermes Agent (shared HTTP daemon)

Run the server once (for example as a systemd user service with MCP_TRANSPORT=http and MCP_HTTP_TOKEN_FILE), put the token in Hermes' .env as TWAKE_CHAT_MCP_TOKEN, then:

mcp_servers:
  twake_chat:
    url: http://127.0.0.1:3995/mcp
    headers:
      Authorization: "Bearer ${TWAKE_CHAT_MCP_TOKEN}"
    timeout: 120
    tools:
      exclude: [send_message, react, edit_message, redact_message, send_file]   # drafts only

Claude Code / Claude Desktop (stdio)

claude mcp add twake-chat --scope user \
  -e MATRIX_USER_ID=@jane:example.com \
  -e "MATRIX_TOKEN_COMMAND=/usr/local/bin/my-token-broker chat-token --json" \
  -- node /path/to/mcp-twake-chat/build/index.js

Do not configure the same device in two clients at once in stdio mode: the second one is refused by the store lock. Use the HTTP daemon instead.

Recommended safe configuration

• For an assistant that acts on its own, keep it to drafts only: exclude send_message, react, edit_message, redact_message and send_file in your MCP client (example above) and let the user send from Twake Chat. Otherwise, ask the assistant to show the exact message and room and wait for your OK.

• Chat messages are written by other people, possibly from other servers through federation: treat them as untrusted input (prompt injection). The tool descriptions say so to the model.

• The access token gives access to your whole history once the recovery key is fetched from the ToM vault: protect the broker's files (0600), never log tokens, and revoke the device from Twake Chat's session list if in doubt.

• Keep the HTTP transport on loopback with a bearer token.

See SECURITY.md.

Usage examples

• "What's unread on the chat? Summarise by room."

• "Who mentioned me since Friday?"

• "Read the last 50 messages of the Atlas project room and list the decisions."

• "Find Bob Martin in the directory."

• "Draft an answer to Alice proposing Tuesday at 10."

• "Download the PDF Bob posted in the Atlas room and summarise it."

Troubleshooting

Development

npm install
npm run build
npm test          # Vitest, no real server needed
node build/index.js check
node scripts/smoke.mjs   # live read-only tour of the tools against your account (counts only)
LIVE_ROOM='!room:server' node scripts/live-write.mjs   # write tools, only in a private room where you are alone

Contributing

Contributions are welcome: read CONTRIBUTING.md and our Code of Conduct. Report vulnerabilities privately as described in SECURITY.md. Release notes are in CHANGELOG.md.

License

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

Copyright © 2026 LINAGORA