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.

Related MCP server: Workel MCP Server

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

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

Resources

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