mattermost-playbooks-mcp

Mattermost Playbooks, as tools an agent can actually use. Playbooks, runs, checklists, assignments, status updates and follow-along — over MCP, with the permissions of whichever account's token you hand it.

  agent  ──MCP──▶  mattermost-playbooks-mcp  ──HTTPS──▶  Mattermost + Playbooks plugin
                       (stdio or http)                    (your token, your rights)

It adds no permission model of its own. Mattermost already knows who may run what — the token is the scope.

Sixty seconds

npx mattermost-playbooks-mcp --url https://team.example.com --token "$MATTERMOST_TOKEN" --team main

Point any MCP client at it:

{
  "mcpServers": {
    "playbooks": {
      "command": "npx",
      "args": ["-y", "mattermost-playbooks-mcp"],
      "env": {
        "MATTERMOST_URL": "https://team.example.com",
        "MATTERMOST_TOKEN": "…",
        "MATTERMOST_TEAM": "main"
      }
    }
  }
}

The token is a personal access token or a bot token. It needs nothing special — no admin, no separate integration, and no Enterprise licence.

What you get

| | | | --- | --- | | Playbooks | write, list, change, duplicate, archive | | Runs without litter | start, hand over, finish — and know what it did to your workspace | | Checklists by name | "tick the one about the migration", not /checklists/2/item/4 | | Assignment | hand one item to a person or another agent | | Status updates | real posts, so @mentions work normally | | Watching | follow a run, or ask what's late | | Scope | read-only, chosen toolsets, chosen teams and playbooks | | Two ways to host it | sidecar per agent, or one shared server |

Playbooks

playbook_create {
  "title": "Release",
  "channelMode": "existing", "channel": "ops",
  "checklists": [
    { "title": "Before", "items": [{ "title": "Freeze main" }, { "title": "Run the suite" }] },
    { "title": "After",  "items": [{ "title": "Announce" }] }
  ]
}

Two rough edges are handled rather than documented: the API refuses a reminder_timer_default_seconds of zero with a 400 that does not name the field (so there is a sane default), and it answers a create with {id} alone — this reads the playbook back so create and get return the same shape.

Runs without litter

A run creates a channel by default, and finishing it does not remove one. A team that experiments with runs ends up with a sidebar of dead channels.

So every run_start tells you which happened:

run_start { "name": "Release 1.2", "playbookId": "p…", "channel": "ops" }
// → "channel": { "attachedTo": "ops" }

run_start { "name": "Release 1.2", "playbookId": "p…" }
// → "channel": { "created": "c…", "note": "finishing this run will NOT remove that channel" }

Finishing says what was left behind, in both senses:

run_finish { "runId": "r…" }
// → { "status": "Finished",
//     "leftUnchecked": ["Publish", "Announce"],
//     "note": "channel c… remains; finishing a run does not remove it" }

Checklists by name

The plugin addresses items positionally — /checklists/2/item/4. An agent would have to re-read the run and count before every call. Here, a number or a title works, and a partial title is enough.

item_check { "runId": "r…", "checklist": "Before", "item": "Run the suite" }
item_check { "runId": "r…", "checklist": 1, "item": 2, "state": "skipped" }

Get it wrong and you are told what is really there:

no item matching "deploy" in "Before". It has: 1. Freeze main; 2. Run the suite

Assignment

item_assign { "runId": "r…", "checklist": "After", "item": "Announce", "assignee": "andrey" }
run_owner_set { "runId": "r…", "owner": "andrey" }
run_participants_add { "runId": "r…", "users": ["sasha"], "joinChannel": true }

The plugin announces an assignment in the run's channel, so the assignee — person or agent — finds out where the team is already looking. And the other direction:

items_mine {}   // every open item assigned to this account, across every run, soonest first

Status updates

A status update is a real Mattermost post, so @name mentions behave exactly as they do anywhere else — no fragile side channel.

run_status_post { "runId": "r…", "message": "Tagged and published. @andrey over to you for the announcement.",
                  "remindInSeconds": 3600 }

remindInSeconds is seconds, and stays seconds. The API actually wants a Go duration in nanoseconds while the playbook's own cadence field is in seconds — two units in one API, converted here so you never meet either.

Need a report from someone else? Ask the plugin to nudge them:

run_request_update { "runId": "r…" }   // → { "asked": "andrey" }

Watching

Follow a run to hear about it without joining it — the cheap way for an agent to keep an eye on someone else's work:

run_follow    { "runId": "r…" }
runs_following {}                  // the morning catch-up, in one call

Ask the questions a standup asks, without reading a single run:

runs_overdue        {}                          // every late open item, with who owns it
runs_changed_since  { "since": "2026-08-13T09:00:00Z" }

There is no blocking wait tool, on purpose: a tool that sleeps holds an agent's whole turn open doing nothing.

Scope

Everything below only ever narrows what the token already permits.

scope:
  readOnly: true                              # every writing tool disappears, and is refused if called
  toolsets: [directory, runs, checklists]     # of: directory, playbooks, runs, checklists, status, monitor, attributes
  teams: [main]
  playbooks: [pabc…]                          # only runs of these playbooks
  denyTools: [playbook_archive]

attributes (playbook and run property fields) is off by default: those endpoints need a Mattermost licence and answer 403 without one. Everything else here works on Team Edition.

Two ways to host it

Sidecar (default). One server per agent, in the agent's own container, reusing the MATTERMOST_TOKEN already there. The agent's reach is exactly that bot account's reach.

Shared. One server for several agents and people:

mattermost-playbooks-mcp --http --host 0.0.0.0 --port 9100

Every request must carry its own Authorization: Bearer <mattermost-token>, and a token in the config is refused at startup rather than used as a fallback. It is stateless: no session id, no server-side store, GET refused because there is no stream to open, and Origin checked.

Configuration

Flags, environment, or a YAML/JSON file — later wins. ${VAR} expands inside the file, so a tracked config holds no secret.

mattermost:
  url: https://team.example.com
  token: ${MATTERMOST_TOKEN}
  team: main

server:
  transport: stdio        # or http
  host: 127.0.0.1
  port: 9100
  path: /mcp

scope:
  readOnly: false
  toolsets: [directory, playbooks, runs, checklists, status, monitor]

log:
  level: warn             # error, warn, info, debug — always on stderr

mattermost-playbooks-mcp --config playbooks.yaml --check    # validate and exit
mattermost-playbooks-mcp --help

Environment: MATTERMOST_URL, MATTERMOST_TOKEN, MATTERMOST_TEAM, PLAYBOOKS_MCP_CONFIG, PLAYBOOKS_MCP_TRANSPORT, PLAYBOOKS_MCP_HOST, PLAYBOOKS_MCP_PORT, PLAYBOOKS_MCP_PATH, PLAYBOOKS_MCP_READ_ONLY, PLAYBOOKS_MCP_TOOLSETS, PLAYBOOKS_MCP_TEAMS, PLAYBOOKS_MCP_PLAYBOOKS, PLAYBOOKS_MCP_DENY_TOOLS, PLAYBOOKS_MCP_LOG_LEVEL.

Requirements

Node 22+. Mattermost with the Playbooks plugin installed and enabled.

It runs on Team Edition. Mattermost refuses to activate it with "this plugin requires a professional license or higher" only while the server is out of testing and developer mode — with ServiceSettings.EnableTesting and EnableDeveloper on, it activates cleanly. (Do not copy those settings to a server with untrusted users: developer mode surfaces JS errors and testing mode adds /test commands.)

Developed against plugin 2.11.1 on Mattermost 11.10.0.

See also

mattermost-boards-mcp — the same idea for Mattermost Boards: boards, cards, properties, comments and mentions. The two are designed to be run side by side.

Develop

npm test        # node --test; no Mattermost needed, and none is contacted

The suite runs against test/fixtures/fake-mattermost.js — a real HTTP server that enforces the plugin's actual rules, including the create that answers with only an id, the positional checklist URLs and the licence 403 on property fields. A stubbed fetch would agree with whatever the client did and prove nothing.

Durable knowledge about this codebase lives in .hint files next to the code and is queried with HINT — hint src/tools/status.js prints what applies before you change it.

Licence

Apache-2.0.