csvql — MCP-сервер для Claude Code: что делает и как установить
Даёт агенту читать CSV через SQL прямо на месте: без импорта, без отдельной базы и без записи в файлы.
Открыть на GitHubЧто делает csvql
Сервер поднимает три инструмента: csv_query принимает SQL, csv_schema отдаёт колонки и несколько строк примера, csv_list перечисляет CSV в каталоге. Запрос идёт по файлу там, где он лежит, так что импортировать ничего не нужно. Внутри один статический бинарник на Zig, сетевого кода в нём нет. Выдача обрезана примерно до 100 строк и 12 KB, поэтому случайный SELECT * не зальёт контекст.
Ставится одной командой csvql install: она прописывает сервер в Claude Code и чужие записи в конфиге не трогает. Дальше Claude Code надо перезапустить. Для VS Code с Copilot те же command и args кладут в .vscode/mcp.json под ключ servers, указав тип stdio; на удалённой машине сервер запускают через ssh, и наружу уходят только SQL и мелкий ответ.
SQL здесь урезанный: нет UNION и оконных функций, внешних join тоже нет, подзапрос работает только в виде col IN (SELECT ...). Такие запросы падают с ошибкой, а не возвращают неверные строки. На входе только CSV. Если до сервера может дотянуться кто-то ещё, --root обязателен: с --root /data выход за каталог отбивается ошибкой PathOutsideAllowedRoot.
Какие задачи решает
- посчитать выручку по клиентам из
sales.csv, не загружая файл в базу - посмотреть колонки незнакомого CSV перед тем, как писать запрос
- узнать, какие CSV лежат в каталоге
/data - ответить на вопрос по файлу на 8 GB, не выгружая его в контекст
- прогнать SQL по данным на сервере через
ssh, не открывая порт
Примеры запросов агенту
- Посчитай через csvql, сколько заказов у каждого клиента в
orders.csv, и покажи первые 10 строк. - Сначала посмотри схему
trips.csv, потом сгруппируй строки поcab_type. - Покажи через
csv_list, какие CSV есть в/data.
Как установить csvql
Установка
Команды запуска нет в реестре MCP — смотрите README репозитория
По шагам, с командами для каждой платформы: Как подключить MCP-сервер: Claude Code, Codex, Cursor, VS Code, Gemini CLI и другие
Вопросы о csvql
Как установить csvql в Claude Code?
Выполнить csvql install, затем перезапустить Claude Code. Команда сама добавит сервер в конфиг, а с --print покажет, что собирается записать, без изменений.
Что делает csvql?
Выполняет SELECT по CSV-файлам прямо в том каталоге, где они лежат, и возвращает агенту несколько строк вместо целого файла. Запись в данные при этом невозможна.
Чем csvql отличается от DuckDB?
Он умеет меньше: UNION, оконные функции и внешние join не поддерживаются, и при необходимости в полном SQL проект отсылает к DuckDB. Взамен в разборщике нет операторов записи, а --root запирает процесс в одном каталоге.
