mm-mcp

An MCP server for Mattermost. It lets an AI agent read and search your Mattermost and, when you allow it, post and reply, as you or as a bot.

mm-mcp is an independent project. It is not affiliated with, endorsed by or supported by Mattermost, Inc.; Mattermost is a trademark of Mattermost, Inc.

The tools read channels, threads, unread posts, mentions and files, search posts, files, people and channels, and, once you allow writes, post, reply, edit, react, pin, keep drafts, join, leave and create channels, and set your status. A link pasted from Mattermost works wherever a tool wants an id, every answer links each post, channel and team it names, and attached files are MCP resources your client can read too. The tools page lists every tool. Views in the chat for clients that render MCP Apps are planned; the issues are the plan.

Why it works the way it does

• Read-only unless you say otherwise. The tools that post or change anything are not offered until MM_MCP_ALLOW_WRITES is true. Then, by default, every change others see asks you first: an agent acting with your token speaks as you to your colleagues. Following a thread, saving a post, a reminder, a draft only you see and the typing indicator are yours alone or gone in seconds, and do not ask. The question is a form your MCP client shows (an MCP elicitation), so posting needs a client that shows one, such as Claude Code in a terminal. MM_MCP_ASK_BEFORE_WRITES=false leaves the asking to your client's own approval instead, for a client that does not show the question, such as Claude Code in the Claude desktop app's Code tab.
• Your token, a bot's, or your own login. A personal access token, a bot token, or your own login through mm-mcp login, single sign-on included, kept in your system's credential store, for servers where personal access tokens are switched off.
• Mattermost's own client. Requests and answers use the server's own Go client and types, not a hand-written description of the API.
• Every supported release, tested. Every tool runs against a real Mattermost Team Edition, on the Extended Support Release and the newest release on every change, and on every release between them each week.
• stdio and Streamable HTTP. A client starts it as a local process, or it serves Streamable HTTP on a loopback address.

Quick start

Install mm-mcp with brew install vriesdemichael/tap/mm-mcp, winget install vriesdemichael.mm-mcp or scoop install vriesdemichael/mm-mcp (after scoop bucket add vriesdemichael https://github.com/vriesdemichael/scoop), or download the binary for your machine from the latest release. Then get a personal access token in Mattermost under Profile → Security → Personal Access Tokens, and keep it in your system's credential store, out of your client's configuration, with mm-mcp login --with paste --url https://chat.example.com. Where those tokens are switched off, log in once with mm-mcp login --url https://chat.example.com instead.

{
  "mcpServers": {
    "mattermost": {
      "command": "mm-mcp",
      "args": ["serve"],
      "env": {
        "MM_URL": "https://chat.example.com"
      }
    }
  }
}

Or, for Claude Code, the plugin, which asks for the address and a token you can leave empty after mm-mcp login:

/plugin marketplace add vriesdemichael/mm-mcp
/plugin install mm-mcp@mm-mcp

or the server alone:

claude mcp add mattermost --scope user --env MM_URL=https://chat.example.com -- mm-mcp serve

Claude Desktop users can open the .mcpb bundle for their machine from the latest release instead.

When it does not work, mm-mcp doctor --url https://chat.example.com checks the configuration, the stored login, the way to the server and the credential, and says what to fix; from inside your MCP client, the diagnose tool does the same with the client's own configuration.

The documentation has every setting, the tools, and the supported Mattermost releases.

Contributing

See CONTRIBUTING.md. The decisions behind how this project is built are in docs/site/adr.

License

Apache-2.0