dungbeetle-mcp

dungbeetle-mcp

The MCP server for Dungbeetle — the snapshot and visual regression testing tool built for AI agents and the humans they work for. It lets a coding agent (Claude Code, Cursor, Codex, Gemini CLI, or any MCP client) list runs, read low-token semantic diffs, check usage, and record reviews — while promoting a baseline stays a human decision unless a human explicitly grants the baselines:write scope.

Setup in 60 seconds

• Get an agent token (a human approves a one-time code in the browser — no secret is ever copy-pasted):

  npx dungbeetle login --label "My agent"
  

• Add the server to your MCP client:

  {
    "mcpServers": {
      "dungbeetle": {
        "command": "npx",
        "args": ["-y", "dungbeetle-mcp"],
        "env": { "DUNGBEETLE_AGENT_TOKEN": "dbat_…" }
      }
    }
  }
  

  Claude Code one-liner: claude mcp add dungbeetle --env DUNGBEETLE_AGENT_TOKEN=… -- npx -y dungbeetle-mcp

Per-client guides: Claude Code · Cursor · Codex · Gemini CLI

Environment

Variable	Meaning
DUNGBEETLE_AGENT_TOKEN	Scoped, revocable agent token from dungbeetle login (recommended)
DUNGBEETLE_CLIENT_ID / DUNGBEETLE_CLIENT_SECRET	Repository client credentials (CI-style alternative)
DUNGBEETLE_SERVER_URL	Only when self-hosting — defaults to https://dungbeetle.dev

stdout is the JSON-RPC channel; diagnostics go to stderr. Missing credentials exit non-zero with guidance.

Why the auth model is different

Agent tokens are minted via an RFC 8628 device flow and scoped: the default Triage preset reads runs/baselines/analytics and writes reviews, but promoting a baseline requires the separate baselines:write scope — so an agent can triage its own visual regressions without ever being able to approve them. Reviews are attributed as "<label> (agent, on behalf of <owner>)", and tokens are revocable from the dashboard at any time. Details: https://dungbeetle.dev/mcp/auth

Machine-readable docs

Full docs index for agents: https://dungbeetle.dev/llms.txt — every docs page also serves raw markdown at its URL + .md. See https://dungbeetle.dev/docs-for-agents.

License

Source-available under the Business Source License 1.1 (converts to Apache-2.0). The Dungbeetle CLI (dungbeetle on npm) is a separate, FSL-licensed package.