mage-debugger-mcp

MCP server for debugging Mage.ai data pipelines from Claude / any MCP host.

Focus: monitoring, logs, error extraction, and run control — not pipeline authoring.

Tools

Category	Tools
Monitoring	list_pipelines, get_pipeline, list_pipeline_runs, get_pipeline_run, list_recent_failures
Logs & errors	get_pipeline_run_logs, get_block_run_logs, tail_logs, get_block_run_error
Control	trigger_pipeline_run, cancel_pipeline_run, retry_pipeline_run
Health	health_check

Install (dev, from source)

uv sync
uv run mage-debugger-mcp

Configure

Mage's auth model: when REQUIRE_USER_AUTHENTICATION=1, the server wants two headers — X-API-Key (OAuth client ID) and OAUTH-TOKEN (user session). An API key alone returns a 403 "invalid scope".

Two ways to provide a session token:

Option A — auto-login (recommended for local dev)

MAGE_API_URL=http://localhost:6789
MAGE_API_KEY=<value of MAGE_API_KEY on the Mage server>
MAGE_EMAIL=admin@admin.com
MAGE_PASSWORD=<your Mage password>

The client calls POST /api/sessions on startup and stashes the minted token.

Option B — paste an existing token

MAGE_API_URL=http://localhost:6789
MAGE_API_KEY=<value of MAGE_API_KEY on the Mage server>
MAGE_OAUTH_TOKEN=<copy from Mage UI DevTools: Application → Cookies → oauth_token>

Use with Claude Code / Desktop

After PyPI publish:

{
  "mcpServers": {
    "mage-debugger": {
      "command": "uvx",
      "args": ["mage-debugger-mcp"],
      "env": { "MAGE_API_URL": "http://localhost:6789", "MAGE_API_KEY": "..." }
    }
  }
}

Local dev path:

{
  "mcpServers": {
    "mage-debugger": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/mageai-mcp", "mage-debugger-mcp"],
      "env": { "MAGE_API_URL": "http://localhost:6789" }
    }
  }
}

License

MIT