QueryPilot MCP

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.

View on GitHub ↗Measured resultsReal sessionConnect your agent

Five read-only tools

list_tables

Every table found in the folder and the file it came from.

describe_table

Columns, types and stats: rows, min, max, average, distinct, % missing.

sample_rows

A few real example rows (max 50).

run_query

One SELECT, max 1,000 rows, stopped after 30 s.

get_definitions

Business terms and column meanings from your semantic.yaml.

Four safety layers

agent→① SQL guard→② locked DuckDB→③ 1,000 rows · 30 s→result+④ audit log

① 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.

Measured results

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.

60 / 60unsafe queries blocked
0leaks of a secret file outside the folder
0 / 41real questions wrongly blocked
41 / 41answers equal to sqlite3 / pandas
1,000rows returned from a 35,717-row table (truncated flag set)
30.0 srunaway query stopped (30 s limit), server kept working
0.922 msSQL guard time per query (median)
5.4 msMCP round trip over stdio (median)

Why two layers

ConfigurationBlockedFiles written into the data folder
SQL guard only (static check)60 / 60n/a
DuckDB lock-down only (guard switched off)42 / 602 (customers_copy.csv, t.parquet)
QueryPilot (both)60 / 600

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:

In the Docker image the folder is also mounted read-only: with the guard off, the same COPY fails with Read-only file system.

Attacks by kind

KindAttacksBlocked
Change data (INSERT, UPDATE, DELETE ...)55
Change tables (DROP, CREATE, ALTER ...)77
Several statements in one call33
Write files (COPY, EXPORT)44
Read files outside the folder, path traversal1212
Read raw files inside the folder44
Network and extensions44
Settings, other databases, metadata1414
Dynamic SQL and other statements77

A real session

Recorded over stdio with the official MCP client on the example folder (scripts/demo_session.py). Every response below is what the server returned.

list_tables ok
{}
{
 "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"
  }
 ]
}
get_definitions ok
{"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": {}
}
describe_table ok
{"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."
}
run_query ok
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
}
run_query ok
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
}
run_query error
DROP TABLE chinook_invoice
{
 "error": "Error executing tool run_query: Blocked: Only SELECT queries are allowed (this is DROP)."
}
run_query error
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}

Try it

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