csvbox-mcp-server

A universal Model Context Protocol (MCP) server for CSVBox. It exposes CSVBox importer-sheet management as MCP tools so you can create, replace, patch, generate, validate, and scaffold importers from any MCP-compatible client — Claude Desktop, Cursor, Windsurf, Roo Code, Cline, VS Code, ChatGPT MCP, and more.

Runs over stdio, so it works the same way in every client.

Tools

CSVBox currently has no GET or LIST endpoints, so there are intentionally no get_sheet / list_sheet tools.

It also exposes two MCP prompts:

Prompt → sheet generation

generate_sheet_json and create_importer_from_prompt use an LLM to convert a free-form request into a complete CSVBox sheet — title, sheet_columns, destinations, webhooks, security_settings, and steps. Only actual data fields become columns; destinations, webhooks, domains, regions, file-upload and step settings are placed in their proper configuration sections, never turned into columns. There are three tiers:

1. Server LLM — when ANTHROPIC_API_KEY or OPENAI_API_KEY is set, the server calls the LLM directly. Works in MCP Inspector and headless.
2. MCP prompt (create_csvbox_sheet) — when you have no server key, host clients (Cursor, Claude Desktop, Cline) run the generation with their own model, then call validate_schema and create_sheet. Free.
3. None configured — generate_sheet_json returns a structured "no LLM provider configured" error pointing to the MCP prompt, and create_importer_from_prompt does not call the CSVBox API. There is no regex fallback.

Category / module expansion

The generator runs in one of two modes, chosen automatically from the prompt:

• Extraction (default) — the prompt names concrete fields (e.g. "columns name, email, phone"). Only those become columns; nothing is invented.
• Expansion — the prompt names business modules / categories as a list (e.g. "modules for: Company Information, Suppliers, Payroll, Invoice"), asks for a comprehensive/detailed schema, or asks for a column count ("at least 100 columns"). Each named module is expanded into several realistic, prefixed, correctly-typed columns (e.g. Suppliers → supplier_id, supplier_name, supplier_gstin, supplier_email, …). An explicit minimum count is honored and every column_name is globally unique.

Data types and validations are inferred from the field names and any requested types:

Large schemas: the default models (claude-haiku-4-5, gpt-4o-mini) are cheap but produce noticeably better 100+ column schemas when you override with a stronger model via LLM_MODEL (e.g. claude-sonnet-4-6). The output cap is raised to fit big sheets; if a request is still too large the response is flagged TRUNCATED (a distinct result, not a parse error) and the CSVBox API is not called — reduce the column count / modules or use a model with a larger output budget and retry.

Function collections (virtual columns, validation functions, data transforms)

Beyond the six sheet properties, the CSVBox Sheet API accepts three collections whose items carry a js_code string that CSVBox executes during an import:

Inside js_code the csvbox object exposes row, column, virtual, user, import, and environment. The two accessors are not interchangeable — a virtual column is per-row and uses csvbox.row.<name> (a scalar), while a "column"-scoped function sees the whole column via csvbox.column.<name> (an array).

Shared optional fields: scope (column | row; not on virtual columns), run_at (before_validation | after_validation; data transforms only), columns / dynamic_columns, active, dependencies, and _delete (PATCH only).

Authoring them

// generate_sheet_functions  (requires ANTHROPIC_API_KEY or OPENAI_API_KEY)
{
  "prompt": "add a virtual column joining first and last name, and check every email contains an @",
  "sheet": { "title": "Customers", "sheet_columns": [ ... ] }
}

Returns { "virtual_columns": [...], "validation_functions": [...], "source": ..., "validation": {...} }. Collections the request does not imply are omitted, never returned as empty arrays.

This tool does not call the CSVBox API. Read the generated js_code, then apply it yourself with patch_sheet. Pass sheet so the model references real column names and the validator can check those references — CSVBox has no read endpoint, so it must be supplied inline. Without an LLM key, use the csvbox_sheet_functions MCP prompt instead.

PUT vs PATCH — read this before applying

Use patch_sheet to apply generated functions. Validate first with the matching verb:

// validate_schema
{ "sheet": { "data_transforms": [ ... ] }, "mode": "patch" }

mode is create (default), put, or patch. It only affects the function collections — under put an empty array is a hard error rather than a warning, and _delete is rejected outside patch.

Dependencies

An item may load up to 5 third-party scripts:

{ "url": "https://cdn.jsdelivr.net/npm/dayjs@1.11.10/dayjs.min.js",
  "globals": ["dayjs"],
  "integrity": "sha384-..." }

Only cdn.jsdelivr.net, unpkg.com, and cdnjs.cloudflare.com are allowed; https only, .js/.mjs path, no query string, fragment, userinfo, or port.

Security. This server never executes js_code — it is an opaque string here. Generated JavaScript is unreviewed model output, so read it before you PATCH it into a live importer. A dependency without an integrity digest can change under your customers at any time; validate_schema warns when one is missing.

See docs/sheet-functions-example.json for a full payload.

Installation

npm install @csvbox/mcp-server

Or build from source:

git clone <this-repo> csvbox-mcp-server
cd csvbox-mcp-server
npm install
npm run build

This produces dist/index.js — the entrypoint MCP clients launch.

Environment variables

Copy .env.example to .env and fill in your CSVBox credentials:

CSVBOX_API_KEY=your_api_key
CSVBOX_API_SECRET=your_api_secret

CSVBox credentials are only required for the API-backed tools (create_sheet, update_sheet, patch_sheet, create_importer_from_prompt). validate_schema and generate_import_code work without any credentials.

Auth header note: the client sends x-csvbox-api-key and x-csvbox-secret-api-key (matching the CSVBox reference payloads). These are defined as constants in src/services/csvbox-api.ts if your account uses different header names.

Client identification

Every request this server sends to the CSVBox API carries two extra headers:

x-csvbox-client: mcp
x-csvbox-client-version: <the version in package.json>

CSVBox records how each sheet was created; without these, sheets and imports made through MCP are indistinguishable from any other REST caller. The version is read from package.json and is the same one the server advertises to your MCP client, so the two can never disagree.