An open-source MCP server that lets AI agents safely explore and query local data files
(CSV, Parquet, Excel, SQLite) with DuckDB. Read-only SELECT, one sandboxed folder, max 1,000 rows,
30-second timeout, and a log of every query. Free and fully local.
Every table found in the folder and the file it came from.
Columns, types and stats: rows, min, max, average, distinct, % missing.
A few real example rows (max 50).
One SELECT, max 1,000 rows, stopped after 30 s.
Business terms and column meanings from your semantic.yaml.
① DuckDB's own parser reads the query: exactly one SELECT, only QueryPilot's tables, an allow-list of table functions.
② The catalog is read-only, file access is off outside the folder, extensions cannot load, and the settings are locked.
③ Row cap and timer. ④ One JSON line per call, blocked calls too.
Real data: Chinook (SQLite, 11 tables), Titanic (CSV, 1,309 rows), Birmingham car parks (Parquet, 35,717 rows) and an Excel workbook. DuckDB 2.0.0, MCP SDK 2.3.0, Python 3.13.18.
| Configuration | Blocked | Files written into the data folder |
|---|---|---|
| SQL guard only (static check) | 60 / 60 | n/a |
| DuckDB lock-down only (guard switched off) | 42 / 60 | 2 (customers_copy.csv, t.parquet) |
| QueryPilot (both) | 60 / 60 | 0 |
DuckDB's "allowed folder" setting allows writing there too, so with the guard off two COPY commands created files.
Some of the 18 queries that ran without the guard:
CREATE TEMP TABLE scratch AS SELECT * FROM chinook_customerCOPY chinook_customer TO '{data}/customers_copy.csv'COPY (SELECT * FROM titanic) TO '{data}/t.parquet' (FORMAT parquet)SELECT * FROM read_text('{data}/semantic.yaml')SELECT * FROM read_blob('{data}/chinook.sqlite')SELECT * FROM glob('{data}/*')SELECT * FROM parquet_metadata('{data}/birmingham_parking.parquet')PRAGMA database_listIn the Docker image the folder is also mounted read-only: with the guard off, the same COPY fails with
Read-only file system.
| Kind | Attacks | Blocked |
|---|---|---|
| Change data (INSERT, UPDATE, DELETE ...) | 5 | 5 |
| Change tables (DROP, CREATE, ALTER ...) | 7 | 7 |
| Several statements in one call | 3 | 3 |
| Write files (COPY, EXPORT) | 4 | 4 |
| Read files outside the folder, path traversal | 12 | 12 |
| Read raw files inside the folder | 4 | 4 |
| Network and extensions | 4 | 4 |
| Settings, other databases, metadata | 14 | 14 |
| Dynamic SQL and other statements | 7 | 7 |
Recorded over stdio with the official MCP client on the example folder (scripts/demo_session.py).
Every response below is what the server returned.
{}{
"tables": [
{
"table": "birmingham_parking",
"source": "birmingham_parking.parquet"
},
{
"table": "chinook_album",
"source": "chinook.sqlite"
},
{
"table": "chinook_artist",
"source": "chinook.sqlite"
},
{
"table": "chinook_customer",
"source": "chinook.sqlite"
},
{
"table": "chinook_employee",
"source": "chinook.sqlite"
},
{
"table": "chinook_genre",
"source": "chinook.sqlite"
},
{
"table": "chinook_invoice",
"source": "chinook.sqlite"
},
{
"table": "chinook_invoice_line",
"source": "chinook.sqlite"
},
{
"table": "chinook_media_type",
"source": "chinook.sqlite"
},
{
"table": "chinook_playlist",
"source": "chinook.sqlite"
},
{
"table": "chinook_playlist_track",
"source": "chinook.sqlite"
},
{
"table": "chinook_track",
"source": "chinook.sqlite"
},
{
"table": "chinook_staff_employees",
"source": "chinook_staff.xlsx"
},
{
"table": "chinook_staff_genres",
"source": "chinook_staff.xlsx"
},
{
"table": "titanic",
"source": "titanic.csv"
}
]
}{"term": "revenue"}{
"terms": {
"revenue": {
"description": "Money from sold tracks (unit price x quantity), before tax. Comes from invoice lines.",
"sql": "SUM(UnitPrice * Quantity) -- table chinook_invoice_line",
"synonyms": [
"sales",
"turnover"
]
}
},
"tables": {}
}{"table": "chinook_invoice_line"}{
"table": "chinook_invoice_line",
"source": "chinook.sqlite",
"row_count": 2240,
"columns": [
{
"name": "InvoiceLineId",
"type": "BIGINT",
"min": "1",
"max": "2240",
"approx_unique": 2273,
"avg": 1120.5,
"std": 646.7766,
"null_percent": 0.0
},
{
"name": "InvoiceId",
"type": "BIGINT",
"min": "1",
"max": "412",
"approx_unique": 409,
"avg": 206.8688,
"std": 119.1349,
"null_percent": 0.0
},
{
"name": "TrackId",
"type": "BIGINT",
"min": "1",
"max": "3500",
"approx_unique": 1950,
"avg": 1717.7344,
"std": 993.798,
"null_percent": 0.0
},
{
"...": "2 more"
}
],
"description": "One row per track bought on an invoice."
}SELECT g.Name AS genre, ROUND(SUM(il.UnitPrice * il.Quantity), 2) AS revenue
FROM chinook_invoice_line il
JOIN chinook_track t ON il.TrackId = t.TrackId
JOIN chinook_genre g ON t.GenreId = g.GenreId
GROUP BY g.Name ORDER BY revenue DESC LIMIT 5{
"columns": [
"genre",
"revenue"
],
"rows": [
[
"Rock",
826.65
],
[
"Latin",
382.14
],
[
"Metal",
261.36
],
[
"Alternative & Punk",
241.56
],
[
"TV Shows",
93.53
]
],
"row_count": 5,
"truncated": false,
"elapsed_ms": 31.8
}SELECT SystemCodeNumber, ROUND(AVG(Occupancy / Capacity), 3) AS occupancy_rate
FROM birmingham_parking GROUP BY 1 ORDER BY 2 DESC LIMIT 3{
"columns": [
"SystemCodeNumber",
"occupancy_rate"
],
"rows": [
[
"BHMBRTARC01",
0.777
],
[
"BHMBCCTHL01",
0.745
],
[
"BHMNCPNHS01",
0.711
]
],
"row_count": 3,
"truncated": false,
"elapsed_ms": 6.1
}DROP TABLE chinook_invoice{
"error": "Error executing tool run_query: Blocked: Only SELECT queries are allowed (this is DROP)."
}SELECT * FROM read_csv('/etc/passwd'){
"error": "Error executing tool run_query: Blocked: Table function 'read_csv' is not allowed (it could read files or settings)."
}Last lines of the audit log from that session:
{"tool": "run_query", "sql": "SELECT SystemCodeNumber, ROUND(AVG(Occupancy / Capacity), 3) AS occupancy_rate\nFROM birmingham_parking GROUP BY 1 ORDER BY 2 DESC LIMIT 3", "status": "ok", "rows": 3, "truncated": false, "ms": 6.1}
{"tool": "run_query", "sql": "DROP TABLE chinook_invoice", "status": "blocked", "reason": "Only SELECT queries are allowed (this is DROP).", "rows": 0, "ms": 0.1}
{"tool": "run_query", "sql": "SELECT * FROM read_csv('/etc/passwd')", "status": "blocked", "reason": "Table function 'read_csv' is not allowed (it could read files or settings).", "rows": 0, "ms": 1.0}
pip install "git+https://github.com/m-shahmeer-kz/querypilot-mcp"
claude mcp add querypilot -- querypilot-mcp --data-dir /path/to/your/data
Setup for Claude Desktop, Cursor, VS Code, Codex CLI, Gemini CLI and Docker is in the README.
MIT licence · by Muhammad Shahmeer