QueryPilot MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| QUERYPILOT_TIMEOUT | No | Query timeout in seconds. Can be lowered, not raised. | 30 |
| QUERYPILOT_DATA_DIR | Yes | Required. The only folder the agent can see. | |
| QUERYPILOT_LOG_FILE | No | Path to the audit log file. Must be outside the data folder. | ~/.querypilot/queries.jsonl |
| QUERYPILOT_MAX_ROWS | No | Maximum number of rows returned. Can be lowered, not raised. | 1000 |
| QUERYPILOT_SEMANTIC | No | Path to an optional semantic.yaml glossary. | <data-dir>/semantic.yaml if it exists |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
QueryPilot gives you READ-ONLY SQL access (DuckDB dialect) to local data files. Suggested workflow:
list_tables to see what exists.
describe_table for columns, types and statistics.
get_definitions to learn business terms (e.g. what "revenue" means here).
sample_rows to look at real values.
run_query with ONE SELECT statement. Results are capped (default 1000 rows) and queries stop after 30 seconds. Write, DDL, file and settings access is blocked.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_tablesA | List every table you can query, with the file it came from. |
| describe_tableB | Show the columns of a table with types and statistics (row count, min, max, average, distinct values, % nulls). |
| sample_rowsB | Return the first n rows of a table (1-50, default 5). |
| run_queryA | 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. |
| get_definitionsA | Business glossary from semantic.yaml: what terms like 'revenue' mean and what each column contains. Leave 'term' empty to get all. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.