Mcp Server Mattermost

mcp-server-mattermost

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

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

[](https://modelcontextprotocol.io/) [](https://pypi.org/project/mcp-server-mattermost/) [](https://hub.docker.com/r/legard/mcp-server-mattermost) [](https://github.com/cloud-ru-tech/mcp-server-mattermost/actions) [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT) [](https://mcp-server-mattermost.readthedocs.io/)

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

Channels (11 tools)

| Tool | Description | Key Parameters | |------|-------------|----------------| | list_public_channels | List public channels in a team | team_id ✓ | | list_my_channels | List your channels with unread counts | team_id ✓, only_unread | | get_channel | Get channel details by ID | channel_id ✓ | | get_channel_by_name | Get channel by name | team_id, channel_name ✓ | | create_channel | Create a new channel | team_id, name, display_name ✓ | | join_channel | Join a public channel | channel_id ✓ | | leave_channel | Leave a channel | channel_id ✓ | | mark_channel_viewed | Mark a channel as viewed (reset unread counters) | channel_id ✓ | | get_channel_members | List channel members | channel_id ✓ | | add_user_to_channel | Add user to channel | channel_id, user_id ✓ | | create_direct_channel | Create DM channel | user_id_1, user_id_2 ✓ |

Messages (5 tools)

| Tool | Description | Key Parameters | |------|-------------|----------------| | post_message | Send a message to a channel | channel_id, message ✓, attachments | | get_channel_messages | Get messages: recent, unread window, or since timestamp | channel_id ✓, unread_only, since | | search_messages | Search messages by term | team_id, terms ✓ | | update_message | Edit a message | post_id, message ✓, attachments | | delete_message | Delete a message | post_id ✓ |

Reactions & Threads (6 tools)

| Tool | Description | Key Parameters | |------|-------------|----------------| | add_reaction | Add emoji reaction | post_id, emoji_name ✓ | | remove_reaction | Remove emoji reaction | post_id, emoji_name ✓ | | get_reactions | Get all reactions on a post | post_id ✓ | | pin_message | Pin a message | post_id ✓ | | unpin_message | Unpin a message | post_id ✓ | | get_thread | Get thread messages | post_id ✓ |

Users (5 tools)

| Tool | Description | Key Parameters | |------|-------------|----------------| | get_me | Get current user info | — | | get_user | Get user by ID | user_id ✓ | | get_user_by_username | Get user by username | username ✓ | | search_users | Search users | term ✓ | | get_user_status | Get online status | user_id ✓ |

Teams (3 tools)

| Tool | Description | Key Parameters | |------|-------------|----------------| | list_teams | List your teams | — | | get_team | Get team details | team_id ✓ | | get_team_members | List team members | team_id ✓ |

Files (3 tools)

| Tool | Description | Key Parameters | |------|-------------|----------------| | upload_file | Upload a file | channel_id, file_path ✓ | | get_file_info | Get file metadata | file_id ✓ | | get_file_link | Get download link | file_id ✓ |

Bookmarks (5 tools) — Requires Entry+ edition

> Note: Requires Entry, Professional, Enterprise, or Enterprise Advanced edition > (not available in Team Edition). Minimum version: v10.1.

| Tool | Description | Key Parameters | |------|-------------|----------------| | list_bookmarks | List channel bookmarks | channel_id ✓ | | create_bookmark | Create link or file bookmark | channel_id, display_name, bookmark_type ✓ | | update_bookmark | Update bookmark properties | channel_id, bookmark_id ✓ | | delete_bookmark | Delete a bookmark | channel_id, bookmark_id ✓ | | update_bookmark_sort_order | Reorder bookmark | channel_id, bookmark_id, new_sort_order ✓ |

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"
      }
    }
  }
}

1. Restart your client

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

Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | MATTERMOST_URL | Yes | — | Mattermost server URL | | MATTERMOST_AUTH_MODE | No | static_token | Auth mode: static_token, client_token, or oauth_proxy | | MATTERMOST_TOKEN | Conditional | — | Bot or personal token. Required for static_token. | | MATTERMOST_TIMEOUT | No | 30 | Request timeout in seconds | | MATTERMOST_MAX_RETRIES | No | 3 | Max retry attempts | | MATTERMOST_VERIFY_SSL | No | true | Verify SSL certificates | | MATTERMOST_LOG_LEVEL | No | INFO | Logging level | | MATTERMOST_LOG_FORMAT | No | json | Log output format: json or text | | MATTERMOST_API_VERSION | No | v4 | Mattermost API version |

For client_token and oauth_proxy modes — including Mattermost OAuth App registration, all MATTERMOST_OAUTH_* settings, and MCP client connection — see [Authentication](docs/authentication.md).

Docker

Stdio mode (default)

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

Claude Desktop config

{
  "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)

docker run -d -p 8000:8000 \
  -e MCP_TRANSPORT=http \
  -e MCP_HOST=0.0.0.0 \
  -e MATTERMOST_URL=https://your-mattermost.com \
  -e MATTERMOST_TOKEN=your-token \
  legard/mcp-server-mattermost

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

HTTP mode with Mattermost OAuth proxy

Register a Mattermost OAuth 2.0 Application first:

| Mattermost field | Production value | |------------------|------------------| | Is Trusted | Yes | | Is Public Client | No | | Callback URLs | https://mcp.example.com/oauth/callback/mm |

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)

| Variable | Default | Description | |----------|---------|-------------| | MCP_TRANSPORT | stdio | Transport: stdio or http | | MCP_HOST | 127.0.0.1 | HTTP bind host (use 0.0.0.0 in Docker) | | MCP_PORT | 8000 | HTTP port |

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](CONTRIBUTING.md) for guidelines.

License

MIT — see [LICENSE](LICENSE) for details.

---

Built with FastMCP · Mattermost API v4

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cloud-ru-tech
• Source: cloud-ru-tech/mcp-server-mattermost
• License: MIT
• Homepage: https://mcp-server-mattermost.readthedocs.io

Install and usage instructions live in the source repository linked above.