AI-powered browser testing via the Model Context Protocol. Point it at any URL (or localhost) and describe what to test — an AI agent browses your app and returns pass/fail with screenshots.

Requires Node.js 20.20.0 or later (transitive requirement from posthog-node@^5.26.0).

Get an API key at debugg.ai, then add to your MCP client config:

{
  "mcpServers": {
    "debugg-ai": {
      "command": "npx",
      "args": ["-y", "@debugg-ai/debugg-ai-mcp"],
      "env": {
        "DEBUGGAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Or with Docker:

docker run -i --rm --init -e DEBUGGAI_API_KEY=your_api_key quinnosha/debugg-ai-mcp

The server exposes 11 tools grouped into Browser (2), Search (3), Projects (3), and Environments (3). The headline tool is check_app_in_browser; the rest manage projects, environments + their credentials, and execution history through a uniform search_* + CRUD pattern.

Runs an AI browser agent against your app. The agent navigates, interacts, and reports back with screenshots. Localhost URLs are auto-tunneled via ngrok.

One focused check per call. The agent has a ~25-step internal budget; split broader suites across multiple calls.

Fires a server-side browser-agent crawl to populate the project's knowledge graph. Localhost URLs tunnel automatically. Returns {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?} with knowledgeGraph.imported === true on successful ingestion.

Each search_* tool has two modes. Pass {uuid} for a single-record detail response. Pass filter params for a paginated summary list. 404 from the backend surfaces as isError: true with {error: 'NotFound', message, uuid}.

projectUuid is optional on search_environments — if omitted, it auto-resolves from the git repo. Credentials are always returned without passwords.

Every filter-mode response is paginated. Response shape:

{
  "filter": { "...echoed query params..." },
  "pageInfo": { "page": 1, "pageSize": 20, "totalCount": 47, "totalPages": 3, "hasMore": true },
  "<items>": [ ... ]
}

Pass optional page (1-indexed, default 1) and pageSize (default 20, max 200; oversized values are clamped). No response is ever silently truncated.

• Passwords are write-only. They never appear in any response body from any tool.
• Tunnel URLs (*.ngrok.debugg.ai) are stripped from all browser-agent responses, including agent-authored text.
• 404s from the backend surface as isError: true with {error: 'NotFound', ...}, never as thrown exceptions.
• Missing DEBUGGAI_API_KEY surfaces as a structured tool error on first invocation — the server still registers and lists tools normally.

v2 collapsed a 22-tool surface to 11. Old-tool → new-tool mapping:

Response-shape changes: the bare count field on list responses is gone — use pageInfo.totalCount.

DEBUGGAI_API_KEY=your_api_key

npm install
npm run build
npm run test:e2e        # real end-to-end evals against the backend

The eval suite spawns the built MCP server as a subprocess, exercises every tool against a real backend, and writes per-flow artifacts to scripts/evals/artifacts/<timestamp>/. See scripts/evals/flows/ for the individual scenarios.

This repo ships a .mcp.json that registers a project-scoped server named debugg-ai-local pointing at node dist/index.js — the freshly-built local code. It only activates when Claude Code's working directory is this repo.

Your other projects should use the user-scoped debugg-ai registration that pulls from the published npm package:

npm run mcp:global      # registers debugg-ai in ~/.claude.json to npx -y @debugg-ai/debugg-ai-mcp

After editing code here, run npm run mcp:local (which just rebuilds) so the next invocation of debugg-ai-local picks up your changes.

Dashboard · Docs · Issues · Discord

Apache-2.0 License © 2025 DebuggAI