Run analytical SQL on local CSV/Parquet/JSON files via mcp-server-duckdb (uvx)

Recipe: Run analytical SQL on local data via mcp-server-duckdb (uvx)

Server: mcp-duckdb-server v1.27.2 Launch: uvx mcp-server-duckdb --db-path /path/to/file.duckdb (stdio, no auth) Tool: query — accepts query (SQL string)

What you get

DuckDB is an in-process OLAP database (like SQLite but optimized for analytics). Through this MCP server you can:

• Create tables and insert data — standard DDL/DML
• Run analytical queries — GROUP BY, window functions, aggregations
• Query files directly — SELECT * FROM read_csv_auto('data.csv'), read_parquet('file.parquet'), read_json_auto('data.json') without any import step
• Persist across calls — the --db-path flag creates a persistent DuckDB file; data survives server restarts

MCP handshake

→ initialize (protocolVersion: "2024-11-05")
← serverInfo: { name: "mcp-duckdb-server", version: "1.27.2" }
→ tools/list
← 1 tool: query
→ tools/call query { query: "CREATE TABLE ...; INSERT INTO ...; SELECT ..." }
← result tuples as Python-style list of tuples

Gotchas

• Results come as Python tuple representation: [('val1', 'val2', 0.95), ...] — parse accordingly.
• Multi-statement queries work (CREATE + INSERT + SELECT in one call).
• The --db-path flag is required; use /tmp/... for ephemeral analysis.

When to use

• Ad-hoc analytics on CSV/Parquet without importing into a database server.
• Agent-driven data exploration — an agent can CREATE TABLE, INSERT findings, then run aggregations.
• Lightweight ETL — read from CSV, transform with SQL, write results.
• Columnar analytics — DuckDB's vectorized engine handles millions of rows in-process.