vibedasher-mcp

An MCP server that exposes the Vibedasher data engine — datasets, CSV upload + ETL, headless SQL query, and dashboard (viz) management — as tools a customer's AI (Claude Code, Cursor, ...) can drive directly.

This is the control plane (VD-601, PIVOT/PLAN.md EP-6). It wraps the published vibedasher Python SDK and calls only the public, metered /api/v1/* API.

Install: pip install vibedasher-mcp — live on PyPI since 2026-08-09, as are vibedasher (PyPI) and @vibedasher/client (npm).

The eject tools (VD-602) ship in this package, not separately: eject_viz, eject_instructions and get_viz_files are registered by register_eject_tools() in eject.py. They pull a viz's code plus an SDK-wiring manifest so your AI can recreate the dashboard natively in your stack.

Tools

run_query reuses the SDK's hand-written query() transport (VD-301): the caller never sees inline-vs-presigned delivery, MessagePack, or retries — one call in, typed rows out. Each dataset id resolves server-side to that dataset's cleanSQLName alias under the VD-203 RLS/alias-rewrite; SQL references only aliases.

Auth

API key only, via X-Api-Key (handled by the SDK's create_client). Set:

export VIBEDASHER_API_KEY=...           # mint via `POST /v1/api-keys` or the console
export VIBEDASHER_REGION=eu-central-1   # or us-east-1
# export VIBEDASHER_BASE_URL=...        # optional override (on-prem/staging)

The key is read once at first tool call and is never logged or echoed in any tool result.

Metering

Every tool hits the public, metered endpoints (create_dataset is credit-gated; run_query is metered via the usage/credits event). The MCP adds no side channel and bypasses no metering.

Run

pip install vibedasher-mcp        # (monorepo dev: also make `vibedasher` importable)
vibedasher-mcp                    # stdio MCP server
# or:  python -m vibedasher_mcp

MCP client config (Claude Code / Cursor):

{
  "mcpServers": {
    "vibedasher": {
      "command": "vibedasher-mcp",
      "env": { "VIBEDASHER_API_KEY": "...", "VIBEDASHER_REGION": "eu-central-1" }
    }
  }
}

Development

The package depends on the sibling SDK at ../sdk/py. Tests wire that path automatically (tests/conftest.py), so from packages/mcp:

python -m pytest tests/ -q

Note: fastmcp is a client-side dependency of this standalone package; it is not bundled into the API Lambdas, so the export_requirements.py step in the root CLAUDE.md does not apply here.