butterstack-mcp

A Model Context Protocol (MCP) server for ButterStack: give an AI assistant read/write access to your game dev pipeline, tasks, builds, and asset approvals.

Zero runtime dependencies. Node builtins only.

Install

Add this to your MCP client's config. No global install needed, npx fetches it on demand:

{
  "mcpServers": {
    "butterstack": {
      "command": "npx",
      "args": ["-y", "butterstack-mcp"]
    }
  }
}

Claude Desktop

Edit claude_desktop_config.json (Settings -> Developer -> Edit Config) and add the block above under mcpServers, then restart Claude Desktop.

Cursor

Add the same block to .cursor/mcp.json in your project, or to your global Cursor MCP settings, under mcpServers.

Antigravity

Add the same block to your Antigravity MCP configuration under mcpServers.

Authentication

Set BUTTERSTACK_API_TOKEN in your client's MCP server environment. This is the primary and recommended way to authenticate: it works standalone, with nothing else installed.

{
  "mcpServers": {
    "butterstack": {
      "command": "npx",
      "args": ["-y", "butterstack-mcp"],
      "env": {
        "BUTTERSTACK_API_TOKEN": "your-token-here"
      }
    }
  }
}

Generate a token from your ButterStack account settings.

If you separately have the ButterStack CLI installed and have already run butter auth login, this server will also pick up the credential it stored on disk (~/.config/butterstack/credentials.json), so you don't have to configure a token twice. But the CLI is not a dependency of this package and installing it is not required: BUTTERSTACK_API_TOKEN alone is enough.

Host

By default the server talks to https://www.butterstack.com. To point it at a self-hosted or local instance, set BUTTERSTACK_HOST:

{
  "env": {
    "BUTTERSTACK_API_TOKEN": "your-token-here",
    "BUTTERSTACK_HOST": "http://localhost:3000"
  }
}

The server refuses to send a stored credential to a host other than the one it was issued for. If you see a "Refusing to send the stored credential" error, either set BUTTERSTACK_HOST to match the host your credential was minted for, or generate a new credential for the host you're pointing at.

Tools

| Tool | Description | |---|---| | projects_list | List all accessible game projects and repositories. | | projects_get | Get status, pipeline configuration, and pending asset counts for a project. | | tasks_list | List tasks, bugs, art backlog, and balance tickets for a project, with filters. | | tasks_create | Create a new bug, feature, or art task card. | | tasks_update | Update status, priority, description, or assignee of an existing task. | | builds_list | List recent CI/CD engine build runs and cook statuses. | | builds_get | Get step timings, exit codes, and commit metadata for a build run. | | builds_investigate_failure | Trigger or fetch AI failure investigation for a failed build, with root cause and blame attribution. | | changes_list | List a project's changes (git commits, Perforce and Lore changelists), filterable by source, identifier, and update time. | | changes_get | Get one change with its files, approvals, linked builds, and tasks. Takes a change id or a commit reference (full SHA, a Perforce build's p4-<n>, or lore-<n>), so a build's commit_hash from builds_get resolves to its change. | | assets_list_pending | List game assets awaiting producer or art lead approval. | | assets_get_details | Inspect an asset's polygon count, texture resolution, preview links, and approval history. | | assets_approve | Approve a submitted game asset version. | | assets_deny | Deny a submitted game asset version with constructive feedback. |

Every tool takes a project_id (except projects_list), which accepts either a numeric project ID or a project name.

The changes_* tools need the read:changes scope. A token issued before that scope was added to the CLI login set does not carry it and gets insufficient_scope: run butter auth login again, or add the scope to your token in account settings.

Prompts

| Prompt | Description | |---|---| | triage_broken_build | Diagnose why the latest build for a project failed and file an attributed task for the author. | | batch_asset_review | Review all pending art submissions for a project against budget constraints. |

Resources

| Resource | Description | |---|---| | butterstack://projects | Live list of all game projects accessible with the current credentials. |

Requirements

Node 18 or later. That's a supported-versions policy, not a hard technical floor: the server only uses builtins compatible back to Node 10.9.0, but 18 is the oldest version this package is actually tested against.

Releases

Publishing is tag-driven, not merge-driven: merging to main publishes nothing. To cut a release, bump version in package.json, commit that, then tag the commit vX.Y.Z to match and push the tag. The tag push runs the test suite, publishes to npm with provenance, and cuts the matching GitHub Release with generated notes.

git commit -am "Bump version to 0.2.0"
git tag v0.2.0
git push origin main --tags

License

MIT