csvql — Claude Code MCP server: what it does, how to install
Lets an agent run SQL over CSV files where they already sit. Nothing gets imported, and nothing gets written back.
Open on GitHubWhat csvql does
Three tools come with it. csv_query takes a SQL string, csv_schema returns the column list with a handful of sample rows, csv_list shows which CSV files a directory holds. Files are read in place, so there is no load step before the first question. The engine is a single static Zig binary with no networking code. Answers are trimmed to roughly 100 rows or 12 KB, which keeps a stray SELECT * from flooding the context.
Setup is csvql install. It registers the server with Claude Code and leaves your other entries alone; restart the client afterwards. VS Code with Copilot wants the same command and args under servers in .vscode/mcp.json, with the type set to stdio. On a remote box you start it over ssh, and only the SQL plus a small result travel the wire.
What you get is a subset of SQL. There is no UNION and no window functions. Outer joins are missing too: an inner hash join is the only one, and a subquery works just as col IN (SELECT ...). Such statements error out instead of returning wrong rows. Input is CSV only. When anyone besides you can reach the process, pass --root: it pins the process to one directory, and a path outside it fails with PathOutsideAllowedRoot.
What it helps with
- total revenue per customer from
sales.csvwithout loading a database - see an unfamiliar CSV's columns before writing the query
- list the CSV files sitting in a directory
- answer a question about an 8 GB file without pasting it into context
- query data on a remote host over
ssh, no open port
Example prompts for the agent
- Group
orders.csvby customer with csvql and show the top 10 by total. - Check the schema of
trips.csvfirst, then count rows percab_type. - List what CSV files are in
/datausingcsv_list.
How to install csvql
Install
The MCP registry has no launch command for it: see the repository README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about csvql
How do I install csvql in Claude Code?
Run csvql install, then restart Claude Code. Add --print if you want to see the config change before it happens.
What does csvql do?
It answers SQL questions about CSV files that stay where they are, handing the agent a few rows rather than the file itself. Write statements do not exist in the parser.
How is csvql different from DuckDB?
Its SQL coverage is narrower: no UNION, no window functions, no outer joins, and the project points you to DuckDB when you need those. In exchange the parser cannot write, and --root confines the process to one directory.
