QueryPilot MCP
Uses DuckDB as the locked-down, read-only SQL engine behind the run_query tool, letting agents run one SELECT statement at a time over the data folder with a 1,000-row cap and a 30 s timeout.
Reads SQLite database files found in the data folder in read-only mode (?mode=ro), exposing each table to the agent (e.g. chinook.sqlite -> chinook_invoice_line) for listing, describing, sampling and querying alongside CSV/Parquet/Excel sources.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@QueryPilot MCP show me the top 10 customers by revenue from the sales CSV"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
QueryPilot MCP
Safety report and real session ↗
An open-source MCP server that lets AI agents (Claude, Cursor, VS Code Copilot, Codex, Gemini CLI ...) safely explore and query your local data files: CSV, Parquet, Excel and SQLite. It uses DuckDB for fast SQL and the official MCP Python SDK. Free and fully local: no cloud, no API keys, no downloads at query time.
Point it at one folder. The agent can look at the tables and run SELECT queries. It cannot change data, write files, read anything outside that folder, or reach the network, and every call is written to a log.
Tools the agent gets
Tool | What it does |
| every table found in the folder, with the file it came from |
| columns, types and statistics (rows, min, max, average, distinct values, % missing) |
| a few example rows (max 50) |
| one read-only |
| your business terms and column meanings from an optional |
All five tools are marked readOnlyHint so the agent's app can show they change nothing.
Related MCP server: mcp-data-analyst
Measured results
Real data: the Chinook music-store database (SQLite, 11 tables), the Titanic passenger list (CSV, 1,309 rows), Birmingham car-park occupancy (Parquet, 35,717 rows) and an Excel workbook (benchmarks/run_benchmarks.py, results.json).
Check | Result |
Unsafe queries blocked (writes, DDL, file read/write, path traversal, network, extensions, settings, dynamic SQL; 9 kinds) | 60 / 60 |
Secret file outside the folder leaked | 0 |
Files created or changed in the data folder | 0 |
Real analytical questions wrongly blocked | 0 / 41 |
Answers equal to the reference (sqlite3 on the original file, or pandas) | 41 / 41 |
Row cap on a 35,717-row table | 1,000 returned, |
Runaway query with the default 30 s limit | stopped at 30.0 s, server kept working |
SQL guard time per query (median) | 0.9 ms |
MCP round trip over stdio, | 5.4 ms |
Why two safety layers? The benchmark also switched the SQL guard off and attacked DuckDB's own lock-down alone: it stopped 42 / 60. The other 18 ran, including 2 COPY commands that wrote new files into the data folder (DuckDB's "allowed folder" setting allows writing there too). With the guard on, 60 / 60 are blocked. And in the Docker image the folder is mounted read-only, so the same COPY fails at the operating-system level too (Read-only file system).
Install
Needs Python 3.11+.
pip install "git+https://github.com/m-shahmeer-kz/querypilot-mcp"
querypilot-mcp --data-dir /path/to/your/data # quick check: it waits for an agent (Ctrl+C to stop)Or from a clone (for development):
git clone https://github.com/m-shahmeer-kz/querypilot-mcp && cd querypilot-mcp
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest # 120 tests
querypilot-mcp --data-dir examples/data # try it on the example dataFind the full path of the command for the configs below with which querypilot-mcp (macOS/Linux) or where querypilot-mcp (Windows). Desktop apps often do not see your terminal's PATH, so use the full path.
Options
Flag | Env variable | Default |
|
| required: the only folder the agent can see |
|
|
|
|
|
|
|
| 1000 (can be lowered, not raised) |
|
| 30 seconds (can be lowered, not raised) |
|
|
Connect it to your agent
In every example, replace /full/path/to/querypilot-mcp and /path/to/your/data.
Claude Code
claude mcp add querypilot -- /full/path/to/querypilot-mcp --data-dir /path/to/your/data
claude mcp list # should show: querypilot ... ✓ Connected(Tested: claude mcp list reported ✓ Connected.)
Claude Desktop
Settings → Developer → Edit Config, then add to claude_desktop_config.json and restart Claude:
{
"mcpServers": {
"querypilot": {
"command": "/full/path/to/querypilot-mcp",
"args": ["--data-dir", "/path/to/your/data"]
}
}
}Cursor
~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
{
"mcpServers": {
"querypilot": {
"command": "/full/path/to/querypilot-mcp",
"args": ["--data-dir", "/path/to/your/data"]
}
}
}VS Code (GitHub Copilot agent mode)
.vscode/mcp.json in your project (note: the key is servers, not mcpServers):
{
"servers": {
"querypilot": {
"type": "stdio",
"command": "/full/path/to/querypilot-mcp",
"args": ["--data-dir", "${workspaceFolder}/data"]
}
}
}OpenAI Codex CLI
codex mcp add querypilot -- /full/path/to/querypilot-mcp --data-dir /path/to/your/dataor in ~/.codex/config.toml:
[mcp_servers.querypilot]
command = "/full/path/to/querypilot-mcp"
args = ["--data-dir", "/path/to/your/data"]Gemini CLI
~/.gemini/settings.json (or .gemini/settings.json in a project):
{
"mcpServers": {
"querypilot": {
"command": "/full/path/to/querypilot-mcp",
"args": ["--data-dir", "/path/to/your/data"]
}
}
}With Docker (any agent)
docker build -t querypilot-mcp .Then use docker as the command. :ro mounts your folder read-only:
{
"mcpServers": {
"querypilot": {
"command": "docker",
"args": ["run", "-i", "--rm", "-v", "/path/to/your/data:/data:ro", "querypilot-mcp"]
}
}
}Use -i (keeps stdin open) and never -d. The image runs as a non-root user.
semantic.yaml (optional)
Agents write good SQL but do not know what your words mean. Put a semantic.yaml in the data folder (full example: examples/data/semantic.yaml):
terms:
revenue:
description: Money from sold tracks (unit price x quantity), before tax.
sql: SUM(UnitPrice * Quantity) -- table chinook_invoice_line
synonyms: [sales, turnover]
tables:
titanic:
description: One row per Titanic passenger.
columns:
pclass: Ticket class (1 = first, 2 = second, 3 = third).get_definitions("sales") then returns the revenue entry, and column notes also appear in describe_table. The file is read with yaml.safe_load, so it can never run code.
How the safety works
agent ──MCP──▶ tool ──▶ ① SQL guard ──▶ ② locked DuckDB ──▶ ③ limits ──▶ result
│ │
└──────────── ④ audit log (every call) ◀──┘SQL guard (
sql_guard.py). DuckDB's own parser reads the query (no fragile text matching). It must be exactly one statement of typeSELECT; every table must be one of QueryPilot's tables or a CTE; table functions are allow-listed (range,generate_series,unnestonly), soread_csv,read_text,glob,query()... are refused;getenvandcurrent_settingare refused.Locked DuckDB (
engine.py). The catalog is opened read-only, file access is switched off except the data folder, extension install/auto-load is off (no network), and the configuration is locked so a query cannot switch any of this back on.Limits. At most 1,000 rows come back (
truncatedtells the agent there were more) and a timer interrupts any query after 30 s.Audit log (
audit.py). One JSON line per call: time, tool, SQL,ok/blocked/error/timeout, reason, rows, milliseconds.
Sandbox (sandbox.py): only files inside the data folder are loaded, hidden files are skipped, and a symlink pointing outside the folder is ignored. QueryPilot never writes inside the data folder (the log must live elsewhere).
File types: CSV/TSV and Parquet become live DuckDB views (nothing copied). Excel sheets are read with pandas + openpyxl, and SQLite tables with Python's sqlite3 in read-only mode (?mode=ro). Table names are simple: chinook.sqlite → chinook_invoice_line, sheet Costs of budget.xlsx → budget_costs.
Project structure
querypilot-mcp/
├── src/querypilot/
│ ├── cli.py # querypilot-mcp command
│ ├── server.py # the 5 MCP tools
│ ├── engine.py # locked DuckDB, row cap, timeout
│ ├── sql_guard.py # SELECT-only allow-list check
│ ├── catalog.py # CSV / Parquet / Excel / SQLite -> tables
│ ├── sandbox.py # one-folder sandbox, safe table names
│ ├── semantic.py # semantic.yaml glossary
│ ├── audit.py # JSONL query log
│ └── config.py # settings and hard limits
├── tests/ # 120 pytest tests (guard, engine, sandbox, log, MCP end-to-end)
├── benchmarks/ # attack + accuracy benchmark, results.json
├── examples/data/ # real example data + semantic.yaml
├── scripts/ # Docker smoke test, demo session recorder
├── docs/ # GitHub Pages report
├── Dockerfile
└── pyproject.tomlTests
pytest # 120 tests, about 11 s
python benchmarks/run_benchmarks.py # about 1 minute (includes one real 30 s timeout)The tests cover: 64 attack queries and 24 normal queries on the guard; read-only and locked settings even without the guard; secret file and symlink outside the folder; row cap and timeout; audit log of blocked calls; config and semantic.yaml errors; and a full end-to-end run that starts the server over stdio and talks to it with the official MCP client. CI runs them on Python 3.11 and 3.13, and builds the Docker image and tests it the same way.
Honest limits
DuckDB's short
PIVOT t ON ...statement is refused (DuckDB reports it as several statements). The SQL-standard formSELECT * FROM t PIVOT (count(*) FOR col IN (...))works.Excel and SQLite files are read once at start-up; restart the server to see changes. CSV and Parquet are always live.
Memory use is not capped by QueryPilot; a very large join can still use a lot of RAM before the 30 s timeout.
Tested with mcp 2.3.0, DuckDB 2.0.0, Python 3.11 / 3.12 / 3.13. The Docker image was tested locally on an Ubuntu 24.04 + Python 3.12 base and in CI on the default
python:3.12-slimbase.
Data credits
Chinook database © Luis Rocha (MIT licence) · Titanic titanic3 from Vanderbilt Biostatistics · Parking Birmingham from the UCI Machine Learning Repository (Open Government Licence v3.0). chinook_staff.xlsx and birmingham_parking.parquet are format copies made by examples/make_example_data.py.
License
MIT © Muhammad Shahmeer
Available Tools
5 toolsdescribe_tableBRead-onlyIdempotent
Show the columns of a table with types and statistics (row count, min, max, average, distinct values, % nulls).
Inputs: table (required). Returns: object
get_definitionsARead-onlyIdempotent
Business glossary from semantic.yaml: what terms like 'revenue' mean and what each column contains. Leave 'term' empty to get all.
Inputs: term. Returns: object
list_tablesARead-onlyIdempotent
List every table you can query, with the file it came from.
Inputs: no named parameters. Returns: object
run_queryARead-onlyIdempotent
Run ONE read-only SELECT (DuckDB SQL) on the tables from list_tables. Returns at most max_rows rows (hard cap 1000); 'truncated' is true if more rows existed. Queries are stopped after 30 seconds.
Inputs: sql (required), max_rows. Returns: object
sample_rowsBRead-onlyIdempotent
Return the first n rows of a table (1-50, default 5).
Inputs: table (required), n. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct stage of the data exploration workflow: discovering tables, inspecting schema/stats, sampling rows, retrieving glossary definitions, and executing SQL. The only mild overlap is between describe_table and get_definitions, but one gives schema/statistics while the other gives business semantics, so an agent can easily choose correctly.
All tool names follow a clear verb_noun pattern (list_tables, describe_table, sample_rows, get_definitions, run_query). The wording is predictable and readable, with no mixed casing or inconsistent verb styles.
Five tools is well-scoped for a read-only DuckDB query assistant. Every tool adds a necessary capability, and there is no redundant or filler tool.
The surface covers the core read-only lifecycle: discover tables, inspect schemas, sample data, understand business terms, and run constrained SELECT queries. Minor gaps exist around searching for columns by name, inspecting relationships/foreign keys, or explaining query plans, but agents can work around these using describe_table and run_query.
Related MCP Connectors
The all-in-one data stack for agents. Upload files, run SQL, evolve tables, and render charts.
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceQuery local CSV, Parquet, JSON and TSV files with real SQL via DuckDB. Gives your AI coding tool ground-truth data access instead of hallucinated answers.5MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients like Claude Desktop, Claude Code and Cursor to safely explore local CSV, Excel, Parquet and SQLite files by running guarded read-only DuckDB SQL over a sandboxed data directory. It also supports data profiling, chart generation as image content, and exporting query results, without ever allowing writes or access outside the configured folder.MIT
- FlicenseNot gradedqualityAmaintenanceEnables LLMs to interact with a local DuckDB database through a single unified SQL query tool, supporting operations such as querying, table creation, joins, and schema inspection. Optional read-only mode enforces native write protection so data can be analyzed safely without unintended changes.-
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to explore and analyse local CSV, Parquet or JSON files through validated read-only SELECT queries, with schema discovery, profiling and query-plan tools. Results are capped, timed, PII-masked and audit-logged inside a locked DuckDB sandbox that cannot write, reach the network or read other files.MIT