duckquery-mcp

An MCP server that exposes a locally-running DuckQuery backend to MCP clients (Claude Code, Cursor, Codex). Start DuckQuery first (desktop app, Docker, or uvicorn main:app --port 48001); this server auto-discovers it.

Run

uvx duckquery-mcp            # zero-install
# or: pipx run duckquery-mcp

Env:

• DUCKQUERY_API_BASE — explicit backend URL (e.g. http://127.0.0.1:48001). Optional; auto-discovered otherwise (runtime.json, then probes 48001/8000/8001).
• DUCKQUERY_MCP_MODE — read-only | normal (default) | full.

Add to a CLI

Claude Code:

claude mcp add duckquery -- uvx duckquery-mcp

Cursor / Codex (mcp.json):

{
  "mcpServers": {
    "duckquery": {
      "command": "uvx",
      "args": ["duckquery-mcp"],
      "env": { "DUCKQUERY_MCP_MODE": "normal" }
    }
  }
}

Claude Desktop — add the same mcpServers block to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "duckquery": {
      "command": "uvx",
      "args": ["duckquery-mcp"]
    }
  }
}

Tools

High-level tools (query, ask, discover, add sources, configure LLM, transform, export) plus a generic duckquery_request passthrough. Safety mode gates which tools are exposed:

• read-only — hides all mutating tools; non-GET duckquery_request calls are hard-blocked (confirm cannot override).
• normal (default) — mutating tools are exposed and run without extra confirmation (run_sql executes write SQL directly); only non-GET duckquery_request passthrough requires confirm=true.
• full — removes the passthrough confirm gate.