csvql-querySAFE
SQL queries for CSV files. The analytical CSV query engine for AI agents cli: csvql.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[](https://github.com/melihbirim/csvql/actions/workflows/ci.yml) [](LICENSE.md) [](https://github.com/melihbirim/csvql/releases)
The analytical CSV query engine for AI agents.
Run SQL analytics — GROUP BY, aggregates, joins, time-series — on CSV files in place: no database, no import, no ingest. csvql ships as an MCP server, so an LLM can query a gigabyte file for a few hundred tokens instead of pasting it (impossible) into context. A single static binary written in Zig. Your data never leaves your machine.
A database is something you load your data into. csvql is a query you run on the data where it already lives.
Read-only and on-prem by design. csvql only runs SELECT — it has no INSERT/UPDATE/DELETE/DROP and physically cannot modify your data. It makes zero network calls, needs no cloud, and runs fully air-gapped. Our next north star: the safe way to give AI agents query access to corporate data — run csvql next to the data on your own servers (read-only, nothing leaves the box) instead of shipping files out to an LLM.
Token economics: query files instead of pasting them
Pasting a 417 MB CSV into an LLM costs 230 million tokens — it fits no context window. Over MCP, the agent queries the file in place and gets back only the answer:
Same answers, ~1,000–500,000× fewer tokens — flat, regardless of file size. One command wires it into Claude: csvql install. Measure it you
f07d63754629OBSERVED · 2026-10-11Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add csvql-query --env TYPESAFE_API_KEY=${TYPESAFE_API_KEY} -- npx -y [email protected]{
"mcpServers": {
"csvql-query": {
"command": "npx",
"args": [
"-y",
"[email protected]"
],
"env": {
"TYPESAFE_API_KEY": "${TYPESAFE_API_KEY}"
}
}
}
}Trust audit
SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | PASS |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | PASS |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (1 observation(s))
- Network
- declared (2 observation(s))
- Shell
- none-observed
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (4)
csv-parse, papaparse
bench/taxi_sample.csv
If you write this kind of slot filling, read your instructions once more imagining the worst possible schema. A file with columns called `value`, `column`, `count` and `group` is not hypothetical.
Gates applied: no_behavioural_pass.
f07d63754629full audit observations/trust-audit/mcp-server/melihbirim__csvql.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-11 | f07d63754629 | SAFE | B | 89 | first audit |
Questions
What is the csvql-query MCP server?
SQL queries for CSV files. The analytical CSV query engine for AI agents cli: csvql.
Is csvql-query safe to connect to an agent?
The audit found nothing in the source that contradicts what it says it does, and graded it B (89/100). Grade A is held back for packages that have also passed a sandboxed behavioural run, which is why a clean server reads B.
What credentials does csvql-query need?
It reads TYPESAFE_API_KEY from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does csvql-query run?
It speaks stdio, so it runs as a local process your client starts. It is published on npm as csvql-query at 2.9.0.
How current is this page?
The grade is for one exact copy of the source (f07d63754629), read on 2026-10-11. The repository is watched and re-audited when it changes.