mattermost-mcp

A local Model Context Protocol (MCP) server that exposes a Mattermost user's full, non-admin capabilities as MCP tools. Runs locally over stdio and authenticates with your Personal Access Token — your token and data never pass through a third party.

Every action runs with exactly the permissions of the token's owner. Admin features (System Console), Integrations (webhooks, OAuth apps, bots, custom slash-command management), and the App Marketplace are intentionally not included.

Target: Mattermost 10.11.9 (REST API v4), Enterprise Edition Free. Works with newer/licensed instances too.

What it covers

83 tools across every user-facing resource group. All tools are prefixed mattermost_.

| Group | Tools | |-------|-------| | Users / profile | users_me, users_get, users_search, users_get_by_usernames, users_update_me, users_get_notify_props, users_update_notify_props | | Channels | channels_list_my, channels_list_public, channels_get, channels_search, channels_create, channels_create_dm, channels_create_gm, channels_members, channels_add_member, channels_remove_member, channels_view, channels_archive, channels_stats | | Posts | posts_create, posts_get, posts_update, posts_delete, posts_list_channel, posts_thread, posts_pinned, posts_pin, posts_unpin | | Reactions | reactions_add, reactions_remove, reactions_list | | Search | search_posts, search_channels, search_users | | Teams | teams_list_my, teams_get, teams_search, teams_join, teams_leave, teams_stats, teams_unread | | Status | status_get, status_get_by_ids, status_set, status_set_custom, status_clear_custom | | Preferences | preferences_list, preferences_get_category, preferences_save, preferences_delete | | Emoji | emoji_list, emoji_get, emoji_search, emoji_autocomplete, emoji_delete | | Files | files_upload, files_get_metadata, files_download, files_get_link, files_search | | Threads (CRT) | threads_list, threads_get, threads_follow, threads_unfollow, threads_mark_read, threads_mark_all_read | | Drafts | drafts_list, drafts_upsert, drafts_delete | | Categories | categories_list, categories_create, categories_delete | | Commands | commands_list, commands_execute | | Bookmarks * | bookmarks_list, bookmarks_create, bookmarks_delete | | Scheduled posts * | scheduled_list, scheduled_create, scheduled_delete | | System (read-only) | system_ping, client_config |

* License-gated on EE Free. Channel bookmarks and scheduled posts (and urgent message priority) require a commercial Mattermost license. These tools are implemented with verified endpoint paths and work on licensed instances; on EE Free the server returns its license error, which is passed through to the caller unchanged.

Quick start (no clone, no install)

The only prerequisite is Node.js (LTS ≥ 20). The server runs straight from npm via npx:

# verify your URL + token work
MATTERMOST_URL=https://mm.example.com MATTERMOST_TOKEN=xxxx npx -y @redcollar/mattermost-mcp check

# print a ready-to-paste config for your client
npx -y @redcollar/mattermost-mcp config claude     # or: cursor | cherry | librechat | (none = all)

Get a token in Mattermost: Profile → Security → Personal Access Tokens → Create Token (the server admin must have enabled Personal Access Tokens). A token acts with the full permissions of your user account.

CLI commands

| Command | Purpose | |---------|---------| | npx -y @redcollar/mattermost-mcp | Run the MCP server on stdio (how clients launch it) | | npx -y @redcollar/mattermost-mcp check | Verify the URL + token (prints ✅/❌, username, team count) | | npx -y @redcollar/mattermost-mcp config [client] | Print a ready-to-paste config (claude, cursor, cherry, librechat) | | npx -y @redcollar/mattermost-mcp help | Usage |

Environment variables

| Var | Required | Default | Purpose | |-----|----------|---------|---------| | MATTERMOST_URL | ✅ | — | Server URL, e.g. https://mm.example.com (no /api/v4) | | MATTERMOST_TOKEN | ✅ | — | Personal Access Token | | MATTERMOST_DEFAULT_TEAM | — | — | Default team (id/name) for team-optional tools | | MATTERMOST_TOOLSET | — | all | CSV of tool domains to enable | | MATTERMOST_ENABLE_WS | — | false | Enable WebSocket realtime tools | | MATTERMOST_TIMEOUT_MS | — | 30000 | HTTP timeout | | MATTERMOST_MAX_RETRIES | — | 3 | Retries for idempotent / 429 / 5xx | | MATTERMOST_PAGE_SIZE | — | 60 | Default page size (max 200) | | MATTERMOST_INSECURE_TLS | — | false | Disable TLS verification (dev only) | | MCP_LOG_LEVEL | — | info | error\|warn\|info\|debug (stderr) |

Add to a client

Paste this into your client config (Claude Desktop claude_desktop_config.json, Cursor ~/.cursor/mcp.json, or .mcp.json):

{
  "mcpServers": {
    "mattermost": {
      "command": "npx",
      "args": ["-y", "@redcollar/mattermost-mcp"],
      "env": {
        "MATTERMOST_URL": "https://mm.example.com",
        "MATTERMOST_TOKEN": "your-personal-access-token"
      }
    }
  }
}

Or, in Claude Code:

claude mcp add mattermost \
  --env MATTERMOST_URL=https://mm.example.com \
  --env MATTERMOST_TOKEN=your-personal-access-token \
  -- npx -y @redcollar/mattermost-mcp

Then restart the client and check it connects.

Which clients work

Local stdio servers run in desktop apps (Claude Desktop, Cursor, Cherry Studio) and self-hosted LibreChat (admin-configured via librechat.yaml).

Usage notes

• Permissions are the user's. The server never escalates privileges. If your account can't do something in the UI, the matching tool returns the server's 403/401 unchanged.
• Identifiers. Most tools accept either ids or names (team, channel, user). Set MATTERMOST_DEFAULT_TEAM to omit team on team-scoped tools.
• Pagination. List tools accept page / per_page (≤200); many accept fetch_all for bounded auto-aggregation.
• Files. files_download returns base64 for content up to 4 MB; for larger files use files_get_link.
• License-gated features. On EE Free, bookmarks / scheduled posts / urgent priority return the server's license error verbatim.
• Each tool returns a short text summary plus structured JSON; errors come back with isError: true and a normalized { status_code, message, request_id } envelope (the token is never echoed).

Local development

cd mattermost-mcp
npm install
npm run build                 # compile TypeScript -> dist/
npm run test:unit             # offline unit tests (config, redaction, CLI)
node scripts/mcp-probe.mjs    # MCP stdio handshake + tools/list smoke test

# Live integration tests against a real Mattermost 10.11.9:
docker compose -f docker-compose.test.yml up -d
node scripts/setup-test-instance.mjs   # creates admin + non-admin user + PAT -> .env.test
npm run test:integration               # 19 live tests (auto-skip without .env.test)
docker compose -f docker-compose.test.yml down -v

Layout

mattermost-mcp/
├── src/
│   ├── index.ts              # CLI dispatcher: server (default) / check / config / help
│   ├── cli.ts                # check / config / help logic
│   ├── config.ts             # env config + validation
│   ├── config-snippets.ts    # per-client config templates (npx-based)
│   ├── registry.ts           # toolset-gated domain registration
│   ├── mattermost/           # REST v4 client, types, id<->name resolve, pagination
│   ├── tools/                # one module per domain (users, channels, posts, ...)
│   └── lib/                  # logging (stderr), redaction, error normalization
└── test/                     # unit tests + test/integration (live)

License

MIT