mcp-server-mattermost 0.5.1

MCP server for Mattermost integration

mcp-server-mattermost

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

38 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

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

3. 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_EXTRA_CA_CERTS	No	—	Path to extra PEM CAs appended to the default trust store
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.

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 for guidelines.

License

MIT — see LICENSE for details.

---

Built with FastMCP · Mattermost API v4