Mattermost MCP Server Setup Guide

An MCP server connects your Mattermost workspace to AI agents securely, without custom API code. Here's how to set it up, configure permissions correctly, and troubleshoot common errors.

What is an MCP Server and Why Connect It to Mattermost?

MCP stands for Model Context Protocol. Think of it as the USB-C for AI: a standard interface that lets large language models interact with your tools, securely, without rewiring your infrastructure every time.

When you connect an MCP server to Mattermost, your AI agent gains structured access to channels, messages, reactions, threads, and files. It can search conversations naturally ("What did we discuss about Q4 roadmap?"), summarize threads, draft posts, or even upload files. Most importantly, the MCP server respects your existing Mattermost permissions: the bot account can only see what its owner can see.

Mattermost released its official MCP server in late 2024 as part of the Agents framework. But you can also use community implementations: the most active is cloud-ru-tech/mcp-server-mattermost (53 stars on GitHub, 39 tools), followed by pvev/mattermost-mcp (44 stars).

Why use MCP instead of webhooks or custom API calls? MCP gives your AI agent tool discovery: it queries what the MCP server can do, rather than you hardcoding API calls. It scales across multiple AI clients (Claude, ChatGPT, Cursor, custom LLM apps) without duplicating integration code. And it enforces Mattermost permissions at the protocol level.

You need it if you're automating incident response (pulling context from #incidents fast), onboarding new team members (searchable knowledge base), or just giving your AI agents read access to team conversations without opening up your API to the world.

What Can the Mattermost MCP Server Do? Capabilities Overview

The top community implementation (cloud-ru-tech) exposes 39 tools across six categories:

Channels: List channels, search by name, get channel info and members, join or leave a channel.

Messages and Reactions: Post messages, edit posts, search messages by keyword or date range, add emoji reactions, get thread information.

Threads: Reply to threads, fetch full thread history with all replies, extract metadata (who replied, when).

Users and Teams: List team members, search users by name or email, get user profiles, manage team membership.

Files: Upload files to channels or threads, list files in a channel, download files (if the bot account has permission).

Bookmarks: Retrieve bookmarked messages and links from a channel.

Each tool accepts structured parameters. For example, the "search_messages" tool takes channel_id, query string, optional date range, and a limit on results. The bot returns structured JSON: message ID, author, timestamp, reaction count. No free-form text parsing needed on the client side.

This matters because your AI agent doesn't have to guess what to do next. It queries the MCP server's schema ("What can you do?"), sees the tools and their parameters, and decides which tool fits the task. If the agent needs to draft a post into #announcements, it checks: "Do I have permission to post messages? Is #announcements a valid channel?" Then it calls the tool and handles the response.

The catch: the MCP server is only as powerful as the permissions you grant the bot account. If the bot can't see private channels, the MCP server can't access them either. This is a feature, not a limitation: it enforces least-privilege security.

Prerequisites: What You Need Before Setup

You'll need four things:

1. A running Mattermost instance. Self-hosted or managed (Opsily runs fully managed Mattermost if you want ops off your plate). You need admin access to create a bot account or generate a personal access token.

2. An AI client that supports MCP. Claude Desktop (macOS/Windows), Cursor IDE, or any custom client that implements the MCP protocol. If you're using just ChatGPT or Claude.com, they don't support external MCP servers yet (you'd need to use the Mattermost Agents plugin instead, built into Mattermost v10.3+).

3. CLI and terminal comfort. Most MCP servers run via Docker, uvx (Python), or npm (JavaScript). You'll be writing a config file (TOML or JSON) and running a command. Not heavy scripting, but comfort with environment variables and config syntax helps.

4. The MCP server code. Choose your implementation: cloud-ru-tech (Python, best documented, most actively maintained) or pvev (JavaScript, includes topic monitoring). Both are open source and run locally or in a container.

Optional but recommended: Docker or a container runtime. Most implementations provide a Dockerfile. It's simpler than managing a Python venv or Node environment.

Step-by-Step Setup for Managed Mattermost

Assuming you're using Opsily's managed Mattermost (or any standard Mattermost instance), here's the process:

Step 1: Create a Bot Account or Personal Access Token

Name it something clear: "mcp-agent" or "ai-assistant". Grant it access to post messages and read channels. For now, make it a system admin or give it explicit permissions to read public channels. (We'll tighten this later.)

After creation, you'll get a token. Copy it. This is your MATTERMOST_TOKEN. Don't share it; treat it like a password.

Alternatively, go to Settings > Personal Access Tokens and generate one for your own account. Personal access tokens are simpler to start with (the MCP server inherits your permissions) but less secure for production (uses your account, not a separate bot). For testing, it's fine. For production, use the bot account.

Step 2: Note Your Mattermost URL and Team ID

Note your Mattermost instance URL (for example, your domain if self-hosted, or the URL from your managed hosting provider).

Your team name or ID. Most teams use a slug like "engineering" or "default". Go to Team Settings (three dots next to team name) to confirm.

For Opsily-hosted Mattermost, this is provided in your console dashboard.

Step 3: Choose and Install the MCP Server

Choose the implementation that best fits your environment. The cloud-ru-tech implementation (Python) is most actively maintained and well-documented. Install it from its GitHub repository via pip, or use the provided Dockerfile for a containerized setup.

Alternatively, the pvev implementation (JavaScript) is available on GitHub and can be installed via npm.

Whichever you choose, follow the repository's README for installation instructions specific to your environment (virtual environment, Docker, system packages).

Step 4: Create Environment Variables

Create a .env file (or export them in your shell):

MATTERMOST_URL=<your-mattermost-url>
MATTERMOST_TOKEN=<your-bot-token-from-step-1>
MATTERMOST_TEAM_ID=engineering

Replace the angle-bracket values with your actual Mattermost URL and token. The MCP server reads these at startup. Don't hardcode them; use environment variables.

Step 5: Run the MCP Server

Start the MCP server according to the implementation you chose. For Python-based servers, this is typically a command like python -m <module-name>. For JavaScript, use npm start. If using Docker, mount the environment variables and run the container.

The server starts on localhost:5000 (or a port you configure). It outputs: "MCP server running at...".

Step 6: Configure Your AI Client

For Claude Desktop, edit ~/.config/Claude/claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mattermost": {
      "command": "python",
      "args": ["-m", "mattermost_mcp"],
      "env": {
        "MATTERMOST_URL": "<your-mattermost-url>",
        "MATTERMOST_TOKEN": "<your-token>",
        "MATTERMOST_TEAM_ID": "engineering"
      }
    }
  }
}

Replace the angle-bracket placeholders with your actual values. Restart Claude Desktop. It auto-connects to the MCP server.

For Cursor, edit .cursor/mcp.json with similar configuration and restart Cursor.

Step 7: Test the Connection

In Claude Desktop (or your AI client), type: "List my Mattermost channels."

The AI agent queries the MCP server, which calls Mattermost's API. You should see a response like: "You have access to #general, #engineering, #sales."

If you see an error ("Connection refused" or "403 Forbidden"), skip to Troubleshooting below.

Authentication Modes: Token vs OAuth vs Client Token

Three ways to authenticate the MCP server to Mattermost.

Static Token (Easiest for Getting Started)

Use a personal access token or bot account token. Set it as an environment variable. The MCP server includes it in every request. Pros: dead simple, no extra setup. Cons: the token lives in config files, needs careful storage, doesn't rotate automatically.

Best for: initial testing, CI/CD pipelines with secret management, bot accounts with minimal permissions.

OAuth (More Secure, Harder to Set Up)

Mattermost supports OAuth 2.0. The MCP server requests a token on your behalf, exchanges an auth code, and gets a time-limited access token. Pros: token is short-lived, renewable, no hardcoded secrets in config files. Cons: requires OAuth client setup in Mattermost (System Console > Integrations > OAuth 2.0 Applications), more moving parts.

Best for: production, teams requiring audit trails, multi-user scenarios where each user's MCP client should act on their own behalf.

To use OAuth: register an OAuth app in Mattermost, configure redirect URIs to your MCP server's callback endpoint, then set environment variables:

MATTERMOST_OAUTH_ID=<client-id>
MATTERMOST_OAUTH_SECRET=<client-secret>

The MCP server will prompt you to authorize on first run.

Client ID + Client Secret (For Service-to-Service)

Some MCP implementations (e.g., for Mattermost Agents plugin) accept a client ID and secret instead of a user token. This is for integrations running as a system service, not a human user. Permissions are determined by the role you assign the app.

Best for: scheduled bots, integrations, unattended workflows.

For most setups, start with a static personal access token or bot account token. OAuth is worth the setup if you're scaling across multiple users.

Permissions and Common Errors

The MCP server can only do what the bot account (or your user account) can do in Mattermost. Permission inheritance is strict.

How Permissions Work

If the bot account can't access #private-channel, the MCP server can't either. The MCP server doesn't bypass permissions; it enforces them.

When you create a bot account, grant it:

channels:read (list and read channels)
posts:create (post messages)
reactions:create (add emoji reactions)
users:read (get user info)
Team membership for any team the bot should access

If the bot is a channel member but the channel is private, it can still see and post. If it's not a member, it can't.

Common Errors and Fixes

403 Forbidden The bot token is invalid or the bot doesn't have permission to perform the action.

Verify the token is correct: copy it again from System Console.
Verify the bot is a member of the channel you're querying.
Verify the bot account is active (not disabled or deleted).

Connection Refused The MCP server isn't running or is listening on a different port/host.

Check that you started the server using the implementation's startup command.
Check the server logs for startup errors (usually print to console).
Verify your Mattermost URL is correct and reachable from your machine.

Team Not Found The team ID or name is wrong or not recognized.

Double-check the team slug (go to Mattermost Team Settings, look at the URL or settings page).
Team names are case-sensitive in some cases. Use the exact name.
If using Opsily managed Mattermost, confirm the team name in your console dashboard.

Token Expired Static tokens expire after 100 days (default in Mattermost). Personal access tokens can be set to expire, or never.

Regenerate the token in System Console or Personal Access Tokens.
Update the environment variable and restart the MCP server.

To Verify Permissions with a Quick Test

From the command line, use curl to test the bot token:

curl -H "Authorization: Bearer <token>" <your-mattermost-url>/api/v4/teams

Replace the angle-bracket placeholders with your token and URL. If the token is valid, you'll get a JSON list of teams. If you get 403 or 401, the token is invalid or the bot lacks permission.

Real-World Use Cases

DevOps Incident Response

Your on-call engineer gets paged at 3am. Instead of manually scrolling through #incidents to find context, they ask Claude Desktop (with the Mattermost MCP connected): "Summarize the last 12 hours of #incidents. What's the current status?"

Claude queries the MCP server, retrieves all messages from #incidents in the past 12 hours, and synthesizes a summary with key decisions and next steps. The engineer saves 10 minutes and has a clear mental model of the outage.

Knowledge Onboarding Bot

A new hire joins. Their onboarding bot (running Mattermost MCP in the background) indexes all messages in #engineering, #design, and #operations channels, then answers questions: "How do we deploy to production?" "What's our incident response process?"

The bot pulls relevant thread discussions, summarizes them, and answers the question without requiring a human to stop and explain.

Automated Status Updates

At end-of-day, an MCP-connected AI agent queries the #updates channel for the past 4 hours, gathers all status posts, then drafts a summary for leadership. Your manager gets a weekly digest without manual copy-paste.

Frequently Asked Questions

What is an MCP server and how does it differ from a webhook?

A webhook is a one-way push: Mattermost sends an event to your app when something happens (new message, reaction added). An MCP server is two-way and pull-based: your AI client asks the MCP server "What can you do?" and then calls specific tools. Webhooks are simpler for event-driven workflows; MCP is better for agents that need to query state and discover capabilities.

Do I need a bot account or a personal access token for Mattermost MCP?

Either works. A personal access token (PAT) is simpler to start with: you inherit your own permissions, no extra account to manage. A bot account is more secure for production: it's a separate identity with minimal permissions, audit trail is cleaner, and you can disable it without losing your own access.

How do I set up MCP for external AI clients like Claude or GPT-4?

Claude Desktop and Cursor IDE support MCP natively. Add the server to their config files (claude_desktop_config.json or.cursor/mcp.json), then restart. ChatGPT and GPT-4 do not support external MCP servers; you'd use the Mattermost Agents plugin instead (built into Mattermost v10.3+).

What permissions does the MCP server need to work correctly?

Minimum: channels:read (list channels), posts:read (read messages). To post or react: add posts:create and reactions:create. To upload files: add files:create. Permissions are inherited from the bot account or user token: the MCP server cannot grant itself extra permissions.

Can I use MCP with a self-hosted Mattermost instance?

Yes. Any Mattermost instance (self-hosted, Opsily managed, or Mattermost Cloud) that's v10.3 or later and has the Agents framework enabled supports MCP servers. Self-hosted instances require you to manage the MCP server yourself (run the Docker container, handle updates, monitor uptime). Managed Mattermost (via Opsily) offloads infrastructure headaches.

How do I authenticate the MCP server with OAuth instead of a static token?

In Mattermost System Console, go to Integrations > OAuth 2.0 Applications. Create a new app, set the redirect URI to your MCP server's callback endpoint. Copy the client ID and secret. Set them as environment variables (MATTERMOST_OAUTH_ID, MATTERMOST_OAUTH_SECRET) and restart the MCP server. On first use, you'll be prompted to authorize.

What error messages are common and how do I fix them?

403 Forbidden means the token is invalid or the bot lacks permission. 401 Unauthorized means the token is missing or expired. Connection Refused means the MCP server isn't running or you have the wrong URL. Team Not Found means the team name or ID is incorrect. Use curl to test the token by replacing placeholder values with your actual Mattermost URL and token. If successful, the token is valid.

Can the MCP server access private channels or only public ones?

Both. If the bot account is a member of a private channel, the MCP server can read and write to it. Permissions are strict: the MCP server respects Mattermost's native channel visibility rules.

The Bottom Line

The Mattermost MCP server is a practical bridge between your AI agents and team conversations. It gives agents safe, structured access to channels and messages without custom API code or permission headaches.

Start with a personal access token and the cloud-ru-tech implementation (most stable, most actively maintained). Set aside 30 minutes to configure environment variables and test a simple query. Then layer OAuth and OAuth role-based access control when you're ready to scale.

If managing Mattermost infrastructure sounds like overhead you don't need, Opsily's managed Mattermost handles the operational burden so you focus on your workflows.

Ready to connect AI to your team? Start with /hosting/mattermost to explore managed Mattermost options.