mcp-server-mattermost

Let AI assistants read, search, and post in your Mattermost workspace

39 tools · Channels · Messages · Reactions · Threads · Files · Users

Features

Channels — list, create, join, manage channels and DMs
Messages — send, search, edit, delete with rich attachments
Reactions & Threads — emoji reactions, pins, full thread history
Users & Teams — lookup, search, status
Files — upload, metadata, download links
Bookmarks — save links and files in channels (Entry+ edition)

Example Queries

Once configured, you can ask your AI assistant:

• "List all channels and find where the deployment discussion is happening"
• "What did I miss in #engineering since yesterday morning?"
• "Show me my unread channels and summarize the threads I was mentioned in"
• "Send a build status alert to #engineering with a red attachment"
• "Search for messages about the outage last week and summarize"
• "Summarize this thread and post the key decisions"
• "Find who worked on the authentication bug last week"
• "Upload the report.pdf to #general and share the link"

Available Tools

Quick Start

1. Get a Mattermost bot token
2. Add to your MCP client config:

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

3. Restart your client

Full setup guide — Claude Desktop, Cursor, Claude Code, Opencode, Docker, pip

Configuration

For client_token and oauth_proxy modes — including Mattermost OAuth App registration, all MATTERMOST_OAUTH_* settings, and MCP client connection — see Authentication.

Docker

Stdio mode (default)

docker run -i --rm \
  -e MATTERMOST_URL=https://your-mattermost.com \
  -e MATTERMOST_TOKEN=your-token \
  legard/mcp-server-mattermost

{
  "mcpServers": {
    "mattermost": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MATTERMOST_URL=https://your-mattermost.com",
        "-e", "MATTERMOST_TOKEN=your-token",
        "legard/mcp-server-mattermost"
      ]
    }
  }
}

HTTP mode (production)

For networked HTTP use per-client auth. static_token over HTTP serves an unauthenticated endpoint acting with the shared token (the server starts but logs a loud warning) — see Authentication → HTTP transport.

docker run -d -p 8000:8000 \
  -e MCP_TRANSPORT=http \
  -e MCP_HOST=0.0.0.0 \
  -e MATTERMOST_AUTH_MODE=client_token \
  -e MATTERMOST_URL=https://your-mattermost.com \
  -e MATTERMOST_HTTP_HOST_ORIGIN_PROTECTION=auto \
  -e MATTERMOST_HTTP_ALLOWED_HOSTS=mcp.example.com \
  legard/mcp-server-mattermost

client_token means each MCP client authenticates with its own Mattermost token, sent as Authorization: Bearer <token> — a client configured without one gets 401. The two MATTERMOST_HTTP_* variables turn on Host/Origin (DNS-rebinding) protection, which is off by default; see HTTP transport security.

Health check: curl http://localhost:8000/health

HTTP mode with Mattermost OAuth proxy

Register a Mattermost OAuth 2.0 Application first:

Then run the MCP server:

docker run -d -p 8000:8000 \
  -e MCP_TRANSPORT=http \
  -e MCP_HOST=0.0.0.0 \
  -e MATTERMOST_AUTH_MODE=oauth_proxy \
  -e MATTERMOST_URL=https://mattermost.internal \
  -e MATTERMOST_OAUTH_MATTERMOST_PUBLIC_URL=https://mattermost.example.com \
  -e MATTERMOST_OAUTH_MCP_PUBLIC_URL=https://mcp.example.com \
  -e MATTERMOST_OAUTH_CLIENT_ID=your-mattermost-oauth-app-id \
  -e MATTERMOST_OAUTH_CLIENT_TYPE=confidential \
  -e MATTERMOST_OAUTH_CLIENT_SECRET=your-mattermost-oauth-app-secret \
  legard/mcp-server-mattermost

If your Mattermost login uses Keycloak SSO, users authenticate through Keycloak inside the Mattermost OAuth login flow. The MCP server does not need a Keycloak client.

Connect Claude Code with Dynamic Client Registration:

claude mcp add --transport http mattermost https://mcp.example.com/mcp

Do not pass --client-id for this server; the MCP client registers with the MCP server, and the MCP server uses the fixed Mattermost OAuth App upstream.

Environment Variables (Docker)

Documentation

📖 mcp-server-mattermost.readthedocs.io

• Quick Start — Installation and setup
• Configuration — Environment variables
• Tools Reference — Detailed API documentation
• llms.txt — AI-readable documentation index

Development

# Clone and install
git clone https://github.com/cloud-ru-tech/mcp-server-mattermost
cd mcp-server-mattermost
uv sync --dev

# Run unit tests
uv run pytest

# Run integration tests (requires Docker or external Mattermost)
uv run pytest tests/integration -v

# Type checking
uv run mypy src/

# Linting
uv run ruff check src/ tests/

# Run locally
MATTERMOST_URL=https://... MATTERMOST_TOKEN=... uv run mcp-server-mattermost

Integration Tests

Integration tests run against a real Mattermost server via Docker (Testcontainers) or external server.

# With Docker (Testcontainers) — automatic setup
uv run pytest tests/integration -v

# Against external Mattermost server
export MATTERMOST_URL=https://your-server.com
export MATTERMOST_TOKEN=your-bot-token
uv run pytest tests/integration -v

# Run specific test module
uv run pytest tests/integration/test_channels.py -v

Integration tests are excluded from the default pytest run. Unit tests run with:

uv run pytest  # Unit tests only

Debugging

Use the MCP Inspector to debug:

npx @modelcontextprotocol/inspector uvx mcp-server-mattermost

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE for details.