DuckDB MCP Server: AI Analytics on Local Files

⏱️ 3 min read 🔌 MCP Server

What it is: MCP servers that put DuckDB — the in-process analytics database — behind your AI agent. The most maintained option is MotherDuck's mcp-server-motherduck, which works against a local DuckDB file or a MotherDuck cloud database; community servers like ktanaka101/mcp-server-duckdb cover the same local ground. Because DuckDB reads CSV and Parquet natively, this is the fastest way to let Claude run real SQL over files on your disk.

Quick answer: Run uvx mcp-server-motherduck --db-path ./analytics.duckdb (or point it at md: for MotherDuck cloud) and your agent can query local CSV/Parquet files with full SQL — SELECT * FROM 'sales_*.parquet' just works, no import step, no warehouse.

Why it matters for data work

Most "can you analyze this file?" tasks don't need a warehouse — they need SQL over a folder of exports. DuckDB's superpower is querying files in place, and through MCP the agent inherits it: it can DESCRIBE a Parquet file, join it against a CSV, compute window functions, and hand back results, all without loading anything into pandas or a server. For quick exploratory analysis this beats spinning up any hosted database.

Install & configure

For Claude Code:

claude mcp add duckdb -- uvx mcp-server-motherduck \
  --db-path ./analytics.duckdb

For Claude Desktop (claude_desktop_config.json) or Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "duckdb": {
      "command": "uvx",
      "args": ["mcp-server-motherduck", "--db-path", "/path/to/analytics.duckdb"]
    }
  }
}

Once connected, ask the agent things like "summarize revenue by month from the Parquet files in ./exports" — DuckDB's glob support (read_parquet('exports/*.parquet')) handles multi-file folders in one query.

Local DuckDB or MotherDuck?

Local mode is free, private, and ideal for files already on your machine. MotherDuck adds a cloud home for the same databases — useful when several people (or several agents) need the same data, with a free tier to start. The same MCP server speaks to both; you switch by changing the connection target to a md: database.

How do I keep it safe?

DuckDB is in-process, so the main risk isn't a production outage — it's the agent modifying local files. Use a read-only flag or connection mode where the server offers one, point the server at a copy of important databases rather than the original, and remember that any file path readable by the server process is queryable by the agent.

Troubleshooting

uvx not found: install uv first (pip install uv or the standalone installer).
File not found in queries: relative paths resolve from the server's working directory — use absolute paths in configs.
Database is locked: another process (a notebook, the DuckDB CLI) holds the file open for writing; close it or query a copy.
MotherDuck auth errors: set the motherduck_token environment variable from your MotherDuck settings page.

Author & links

Author: MotherDuck (official server) plus community implementations

Repo: github.com/motherduckdb/mcp-server-motherduck

License: MIT

Related skills

For client-server databases, see the Postgres MCP server and SQLite MCP server (DuckDB's OLTP sibling). Warehouse-scale data belongs with the Snowflake MCP server or BigQuery MCP server.

← Back to MCP Servers