# csvql

Lets an agent run SQL over CSV files where they already sit. Nothing gets imported, and nothing gets written back.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 30
- Author: melihbirim
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/melihbirim/csvql
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/csvql

## What it 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`.

## Install

### Claude Code (native platform)

**Install**
- The MCP registry has no launch command for it: see the repository README

## When to use it
- total revenue per customer from `sales.csv` without 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
- Group `orders.csv` by customer with csvql and show the top 10 by total.
- Check the schema of `trips.csv` first, then count rows per `cab_type`.
- List what CSV files are in `/data` using `csv_list`.

## Similar
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408
- [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89433
- [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16717
- [PostHog MCP Server](https://affpapa.org/en/nevibecode/mcp/posthog-mcp-server.md) — MCP server · ★ 40409
- [dbx](https://affpapa.org/en/nevibecode/mcp/dbx.md) — MCP server · ★ 27669
- [Metabase](https://affpapa.org/en/nevibecode/mcp/metabase.md) — MCP server · ★ 49845

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md