mattermost-mcp

A Model Context Protocol server for Mattermost. It lets an AI agent (Claude, Cursor, VS Code, any MCP client) catch up on your unreads and mentions, read channels, threads and DMs, and search. If you switch write mode on, the agent can also post, reply, send DMs, edit its own messages and react.

• Read-only by default. Write tools are not even registered until you set MATTERMOST_ENABLE_WRITE=1. Even then, the agent can only edit posts written by your own account.
• Sees what you see. Unread counts match the client badge (muted channels are skipped, collapsed-thread counts are used) and sidebar categories work as filters. Mentions from muted channels are still shown.
• Works where personal access tokens don't. Use a personal access token (PAT) or bot token if you can. If an admin has disabled PATs, or a proxy strips the Authorization header, use your browser session cookies instead.
• Fast. Channel metadata is fetched once, across teams in parallel, and cached briefly. No per-channel requests.

Quick start

1. Create a personal access token in Mattermost: Profile → Security → Personal Access Tokens → Create Token. If that section is missing, an admin must enable System Console → Integrations → Integration Management → Enable Personal Access Tokens (or see Cookie auth).
2. Install uv.
3. Add the server to your client.

Claude Code

claude mcp add mattermost \
  -e MATTERMOST_URL=https://mattermost.example.com \
  -e MATTERMOST_ACCESS_TOKEN=your-token \
  -- uvx mattermost-mcp-server

Claude Desktop (claude_desktop_config.json), Cursor (~/.cursor/mcp.json) and other clients that use mcpServers:

{
  "mcpServers": {
    "mattermost": {
      "command": "uvx",
      "args": ["mattermost-mcp-server"],
      "env": {
        "MATTERMOST_URL": "https://mattermost.example.com",
        "MATTERMOST_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "inputs": [
    { "type": "promptString", "id": "mm-token", "description": "Mattermost access token", "password": true }
  ],
  "servers": {
    "mattermost": {
      "command": "uvx",
      "args": ["mattermost-mcp-server"],
      "env": {
        "MATTERMOST_URL": "https://mattermost.example.com",
        "MATTERMOST_ACCESS_TOKEN": "${input:mm-token}"
      }
    }
  }
}

Then try asking: "What did I miss in Mattermost today?" or "Summarize the thread about the release in #engineering."

To let the agent post, add "MATTERMOST_ENABLE_WRITE": "1" to env (see Write mode).

Tools

Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint), so clients can auto-approve reads and ask before writes. Nothing can delete posts, change channels or perform admin actions.

Write mode

Write mode is off unless MATTERMOST_ENABLE_WRITE is 1, true, yes or on. When it is off:

• the five write tools are not registered, so the model never sees them;
• the HTTP client refuses every request that is not a GET or one of the read-only POSTs (user lookup, user search, post search), before anything is sent.

The one server-side effect of read-only mode is the same as in any Mattermost client: get_direct_messages with someone you have never messaged creates the (empty) DM channel between you.

When write mode is on, update_post checks the post's author and refuses any post that is not yours, even if your account has permission to edit other people's posts. Posts are written as the authenticated user (or bot), so consider a dedicated bot account for agents that post on their own.

Configuration

Choosing the auth mode. If MATTERMOST_AUTH_MODE is unset, the first credential source that has any credential decides. The sources are checked in order: env, then cookie host, then keychain. MATTERMOST_ACCESS_TOKEN in that source means token mode. MATTERMOST_TOKEN alone means cookie mode. A lower-priority source never overrides a higher one.

Cookie auth

Use this when personal access tokens are disabled on your server, or when a reverse proxy strips the Authorization header.

1. Log in to Mattermost in a browser and open DevTools → Application → Cookies.
2. Copy MMAUTHTOKEN, MMCSRF and (optionally) MMUSERID into MATTERMOST_TOKEN, MATTERMOST_CSRF and MATTERMOST_USER_ID.

Session cookies expire. When they do, tool calls fail with a 401 error. Put fresh cookies wherever the server reads them from, then restart it, because env is read only once. If something rotates cookies for you, describe it in MATTERMOST_AUTH_HELP so the agent knows what to do.

Credential sources

The server resolves each field separately. The first source that has a value wins:

1. Environment variables, as above.

2. Cookie host (off by default). A plain KEY=VALUE file with the same variable names, kept on another machine and read over ssh. Use this when one machine rotates the credential and others just consume it. The result is cached locally. On a 401 the server pulls the file again and retries once. ssh runs with BatchMode=yes, so a locked key fails fast instead of hanging the MCP handshake, and the reason goes to stderr. The file may only supply MATTERMOST_URL, MATTERMOST_ACCESS_TOKEN, MATTERMOST_TOKEN, MATTERMOST_CSRF and MATTERMOST_USER_ID. Nothing else is read from it, not even the auth or write mode.

3. OS keychain: accounts url, access_token, token, csrf and user_id under the service MATTERMOST_KEYCHAIN_SERVICE.

   # macOS
   security add-generic-password -s mattermost-mcp -a url          -w https://mattermost.example.com
   security add-generic-password -s mattermost-mcp -a access_token -w <personal access token>
   # Linux (pass)
   pass insert mattermost-mcp/url
   pass insert mattermost-mcp/access_token
   

Troubleshooting

• Mattermost rejected the access token (401): the token was revoked or mistyped. Create a new one, or check whether your account is still allowed to use personal access tokens.
• Mattermost rejected the session cookies (401): the browser session expired. Copy fresh cookies and restart the server.
• Write tools in cookie mode need the MMCSRF cookie: set MATTERMOST_CSRF. Mattermost requires it for any change made with cookie auth.
• write mode is disabled: set MATTERMOST_ENABLE_WRITE=1 and restart the client.
• Requests time out behind a corporate proxy: the server honours HTTPS_PROXY/ALL_PROXY, including SOCKS. If that proxy should not be used for Mattermost, set MATTERMOST_TRUST_ENV=0.
• Nothing happens in Claude Desktop: GUI apps do not inherit your shell PATH. Use the full path to uvx (which uvx) as command.

Development

git clone https://github.com/toffguy77/mattermost-mcp.git
cd mattermost-mcp
uv sync
uv run pytest
uv run ruff check

Run your local checkout from a client with uv run --project /path/to/mattermost-mcp mattermost-mcp. python -m mattermost_mcp works too. The tests never touch the network or ssh: HTTP is mocked with respx. See CONTRIBUTING.md, CHANGELOG.md and SECURITY.md.

License

MIT