claude-channel-mattermost
한국어 | English
An MCP server that connects Mattermost to Claude Code — send and receive messages, manage files, and control access through a bot account.
Features
- Messaging bridge — forward Mattermost DMs and channel messages to Claude Code, reply back with auto-chunking and threading
- 5 built-in tools — reply, react, edit, fetch history, download attachments
- Multi-layer access control — pairing codes, allowlists, per-channel gating, and static mode
- Plan mode —
!plan / !go / !cancel workflow for review-before-execute
- Per-chat notes — channel-scoped context persistence across sessions
- Multi-channel router — optional daemon that spawns isolated Claude instances per channel
- Zero build step — runs directly with Bun, no compilation required
Prerequisites
- Bun >= 1.0:
curl -fsSL https://bun.sh/install | bash
- Mattermost server (self-hosted or cloud) with bot account support enabled
Quick Start
1. Create a bot account
System Console → Integrations → Bot Accounts → Enable Bot Account Creation.
Then: Integrations → Bot Accounts → Add Bot Account. Give it a username (e.g. claude-bot).
2. Generate a token
After creating the bot, copy the Access Token — it's only shown once.
3. Invite the bot
In channels where you want the bot to respond:
/invite @claude-bot
4. Install the plugin
/plugin install mattermost@claude-plugins-official
5. Configure credentials
/mattermost:configure https://your.mattermost.server.com xxxxxxxxxxxxxxxxxxxxxxxxxxx
This writes MATTERMOST_URL and MATTERMOST_TOKEN to ~/.claude/channels/mattermost/.env.
You can also set environment variables directly (shell env takes precedence).
Multiple instances: set MATTERMOST_STATE_DIR to a different directory per instance.
6. Launch
claude --channels plugin:mattermost@claude-plugins-official
7. Pair
DM the bot on Mattermost. It replies with a 6-character code. In Claude Code:
/mattermost:access pair <code>
8. Lock it down
Once everyone who needs access is paired, switch to allowlist mode:
/mattermost:access policy allowlist
Tools
| Tool | Description |
|---|
reply | Send message to a channel. Supports reply_to/thread_id for threading, files for attachments (max 10, 50MB each). Auto-chunks at 16383 chars. |
react | Add emoji reaction by message ID. Use short names without colons: thumbsup not :thumbsup:. |
edit_message | Edit a message the bot previously sent. Bot's own messages only. |
fetch_messages | Pull recent history (oldest-first, max 200/call). Includes message IDs and attachment markers. |
download_attachment | Download attachments from a message to ~/.claude/channels/mattermost/inbox/. Returns paths + metadata. |
Inbound messages trigger a typing indicator automatically.
Access Control
DM Policies
| Policy | Behavior |
|---|
pairing (default) | Reply with a 6-char code, drop the message. Approve with /mattermost:access pair <code>. |
allowlist | Drop silently. For when everyone who needs access is already listed. |
disabled | Drop everything, including allowlisted senders and group channels. |
Group Channels
Off by default. Opt in per channel ID:
/mattermost:access group add <channelId>
With requireMention: true (default), the bot only responds when mentioned or replied to.
Mention Detection
- Plain text
@botname in the message
- Thread reply to a recent bot message (last 200 tracked)
- Custom regex via
mentionPatterns
Skill Commands
| Command | Effect |
|---|
/mattermost:access | Show current state |
/mattermost:access pair <code> | Approve pairing code |
/mattermost:access deny <code> | Discard pending code |
/mattermost:access allow <userId> | Add to allowlist |
/mattermost:access remove <userId> | Remove from allowlist |
/mattermost:access policy <name> | Set DM policy |
/mattermost:access group add <id> | Enable group channel |
/mattermost:access group rm <id> | Disable group channel |
/mattermost:access set <key> <val> | Set delivery config |
User IDs: Mattermost alphanumeric strings. Find via profile popover → three-dot menu → Copy ID.
Configuration
Environment Variables
