# csvql [Health: Active]

**Category:** 🗄️ Databases  
**Repository:** https://github.com/melihbirim/csvql  
**GitHub Stars:** 30  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/csvql

## Description
Query CSV files with SQL via MCP. Fast, local, zero-config, read-only, sandboxable with --root.

## Claude Desktop Quick Installation
No confirmed install details yet, so no config is published. Follow the setup steps in the repository above.

## Documentation

## What the csvql MCP server does

The csvql MCP server gives an MCP client access to CSV files where they already reside. An agent can submit SQL that names files with single-quoted paths, inspect a file's columns and sample rows, or list CSV files in a directory. Queries are read-only: the engine does not provide INSERT, UPDATE, DELETE, or DROP operations, and it does not modify input files.

The server is suited to local or on-premise data analysis when uploading a file or maintaining a database connection is undesirable. It can run beside the files on a workstation or server, and an MCP client can invoke it through SSH so that only the SQL request and small result travel across the connection.

## How it works

Run the executable with `--mcp` and register it as a stdio MCP server. The available tools are:

- `csv_query(sql)`, which returns query results as JSON.
- `csv_schema(file)`, which reports column names and several sample rows.
- `csv_list(directory?)`, which lists CSV files in a directory.

MCP query responses are limited to about 100 rows or 12 KB per call. This keeps large scans from directly flooding the agent context, although the SQL still runs against the source file. The process makes no network calls according to the project documentation, and the executable is distributed as a static Zig binary.

Use `--root /data` to restrict file access to a directory. Paths outside that root, including traversal attempts, fail. For remote or shared use, the project recommends combining the root restriction with an unprivileged operating-system user and a read-only mount.

## Setup and configuration

Install with Homebrew, download a platform binary from GitHub Releases, build from source with Zig 0.15.2, or install the related Python and Node.js libraries. For MCP use, the built-in `csvql install` command registers the server with Claude Code and Claude Desktop when the relevant configuration is available. A manual configuration supplies the executable path and arguments such as `--mcp` and `--root`.

VS Code Copilot uses the same command and argument values under its `servers` configuration with a stdio type. Claude Desktop also has a downloadable MCP bundle option. The `--audit <file>` flag appends one JSONL record for each query. Other relevant options include delimiter selection, output formatting, strict parsing, thread count, schema inspection, and input-header handling.

## Tools and capabilities

SQL supports selecting columns, filtering, ordering, limiting, grouping, aggregates, date functions, and inner hash joins between CSV files. A restricted `IN (SELECT ...)` subquery form is supported. CSV files can be read from disk or standard input using `-` as the input path. Tab-separated input is possible by changing the delimiter. Command-line output can be CSV, JSON, JSONL, or Markdown; MCP tool results are JSON.

The csvql MCP server processes data in place rather than ingesting it. The documentation reports flat memory use for aggregate queries in its benchmark, including approximately 74 MB on files ranging from 0.7 GB to 8 GB. These figures are project benchmarks, not a guarantee for every query or workload.

## Limitations and notes

Input is limited to CSV; JSON and JSONL are output formats, not input formats. SQL does not include UNION, window functions, or left, right, full, or cross joins. Only inner joins are available. Scalar functions in `WHERE` are limited to `DATEDIFF`, `DATEADD`, and `EXTRACT`; other documented functions may be available in the select list but fail in filters.

Quoted CSV is slower than unquoted input, and `MEDIAN` buffers every value in a group. Very high-cardinality grouping can also be slower. The result cap prevents a single MCP response from returning an entire large file, so workflows requiring unrestricted exports should use the command-line interface or another data tool.

_Full upstream README: https://allmcps.com/mcp/csvql/readme_