Manage CSVBox importer sheets by creating, updating, validating, and generating schemas using natural language prompts.
Also known as csvbox-io/csvbox-mcp-server, @csvbox/mcp-server
- Stars
- 1
- Tools
- 9
- Downloads, 30 days
- 150
- Latest version
- 1.0.1
- Last commit
- Oct 23, 2026
- License
- MIT
What is CSVBox MCP?
CSVBox manages CSVBox importer sheets by creating, updating, validating, and generating schemas using natural language prompts. It exposes 9 tools, such as create_sheet, update_sheet, patch_sheet.
Summary generated from the project's README
About CSVBox MCP server
Managing CSVBox importer sheets through natural language is what this server enables for developers using MCP-compatible clients like Claude Desktop, Cursor, or Windsurf. It provides a bridge to create, update, patch, and validate importer schemas without writing manual JSON configurations. By using tools like create_sheet and patch_sheet, you can manage your importers directly from your coding environment.
The server supports two ways to handle AI-driven generation. You can provide an Anthropic or OpenAI API key to let the server call an LLM directly for tasks like generate_sheet_json, or you can use built-in MCP prompts to let your host client's own model handle the heavy lifting. This makes it flexible for both headless environments and interactive desktop clients.
Beyond basic schema management, the server helps author complex logic including virtual columns, validation functions, and data transforms. It includes a validate_schema tool to check your work locally before applying changes to your live CSVBox account. Because the server runs over stdio, it integrates easily into existing local development workflows.
What you can do with it
- 1Generate complete importer schemasConvert a simple text description of business modules into a fully structured CSVBox sheet JSON.
- 2Author complex data logicCreate JavaScript-based virtual columns and validation functions using natural language prompts.
- 3Validate schemas locallyCheck the integrity of your sheet configuration and function collections before pushing them to the API.
- 4Generate integration codeProduce ready-to-use code snippets for React, Vue, or Angular to integrate your importer.
Written from the project's README. Every use case is checked against a quote from it.
How to install CSVBox MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall CSVBox MCP in Claude Code
$ claude mcp add --env 'CSVBOX_API_KEY=<YOUR_CSVBOX_API_KEY>' --env 'CSVBOX_API_SECRET=<YOUR_CSVBOX_API_SECRET>' --env 'ANTHROPIC_API_KEY=<YOUR_ANTHROPIC_API_KEY>' --env 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' csvbox-mcp-server -- npx -y @csvbox/mcp-serverInstall CSVBox MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"csvbox-mcp-server": {
"command": "npx",
"args": [
"-y",
"@csvbox/mcp-server"
],
"env": {
"CSVBOX_API_KEY": "<YOUR_CSVBOX_API_KEY>",
"CSVBOX_API_SECRET": "<YOUR_CSVBOX_API_SECRET>",
"ANTHROPIC_API_KEY": "<YOUR_ANTHROPIC_API_KEY>",
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}Install CSVBox MCP in VS Code
.vscode/mcp.json
{
"servers": {
"csvbox-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@csvbox/mcp-server"
],
"env": {
"CSVBOX_API_KEY": "<YOUR_CSVBOX_API_KEY>",
"CSVBOX_API_SECRET": "<YOUR_CSVBOX_API_SECRET>",
"ANTHROPIC_API_KEY": "<YOUR_ANTHROPIC_API_KEY>",
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}Install CSVBox MCP in VS Code CLI
$ code --add-mcp '{"name":"csvbox-mcp-server","type":"stdio","command":"npx","args":["-y","@csvbox/mcp-server"],"env":{"CSVBOX_API_KEY":"<YOUR_CSVBOX_API_KEY>","CSVBOX_API_SECRET":"<YOUR_CSVBOX_API_SECRET>","ANTHROPIC_API_KEY":"<YOUR_ANTHROPIC_API_KEY>","OPENAI_API_KEY":"<YOUR_OPENAI_API_KEY>"}}'Install CSVBox MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"csvbox-mcp-server": {
"command": "npx",
"args": [
"-y",
"@csvbox/mcp-server"
],
"env": {
"CSVBOX_API_KEY": "<YOUR_CSVBOX_API_KEY>",
"CSVBOX_API_SECRET": "<YOUR_CSVBOX_API_SECRET>",
"ANTHROPIC_API_KEY": "<YOUR_ANTHROPIC_API_KEY>",
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}Install CSVBox MCP in Codex
$ codex mcp add csvbox-mcp-server --env 'CSVBOX_API_KEY=<YOUR_CSVBOX_API_KEY>' --env 'CSVBOX_API_SECRET=<YOUR_CSVBOX_API_SECRET>' --env 'ANTHROPIC_API_KEY=<YOUR_ANTHROPIC_API_KEY>' --env 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' -- npx -y @csvbox/mcp-serverInstall CSVBox MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.csvbox-mcp-server] command = "npx" args = ["-y", "@csvbox/mcp-server"] [mcp_servers.csvbox-mcp-server.env] CSVBOX_API_KEY = "<YOUR_CSVBOX_API_KEY>" CSVBOX_API_SECRET = "<YOUR_CSVBOX_API_SECRET>" ANTHROPIC_API_KEY = "<YOUR_ANTHROPIC_API_KEY>" OPENAI_API_KEY = "<YOUR_OPENAI_API_KEY>"
Install CSVBox MCP in Gemini CLI
$ gemini mcp add -s user -e 'CSVBOX_API_KEY=<YOUR_CSVBOX_API_KEY>' -e 'CSVBOX_API_SECRET=<YOUR_CSVBOX_API_SECRET>' -e 'ANTHROPIC_API_KEY=<YOUR_ANTHROPIC_API_KEY>' -e 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' csvbox-mcp-server npx -- -y @csvbox/mcp-serverInstall CSVBox MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"csvbox-mcp-server": {
"command": "npx",
"args": [
"-y",
"@csvbox/mcp-server"
],
"env": {
"CSVBOX_API_KEY": "<YOUR_CSVBOX_API_KEY>",
"CSVBOX_API_SECRET": "<YOUR_CSVBOX_API_SECRET>",
"ANTHROPIC_API_KEY": "<YOUR_ANTHROPIC_API_KEY>",
"OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @csvbox/mcp-server 1.0.1 in an isolated container with no network and no keys. It answered and listed 9 tools.
CSVBox MCP tools 9
Read from the server with tools/listcreate_sheetCreate a new CSVBox sheet via POST /1.1/sheet. Input: { sheet }. Returns the API response.
update_sheetReplace an existing CSVBox sheet via PUT /1.1/sheet/{sheet_license_key}. Input: { sheet_license_key, sheet }. Returns the API response. DESTRUCTIVE: PUT is authoritative for every collection it sends — items listed are created or updated in place, and any existing item the array does not name is DELETED. This applies to virtual_columns, validation_functions and data_transforms: sending an empty array DELETES ALL of that collection's items, while OMITTING the key leaves them untouched. `_delete` is not valid here; use patch_sheet to remove a single item. Run validate_schema with mode 'put' first to catch a destructive body.
patch_sheetPartially update a CSVBox sheet via PATCH /1.1/sheet/{sheet_license_key}. Sends only the changes object. Input: { sheet_license_key, changes }. Returns the API response. PATCH MERGES: only the items you list are touched and nothing is deleted implicitly, so an empty array is a no-op. Items in virtual_columns, validation_functions and data_transforms are matched by column_name / function_name / transform_name respectively — an unmatched name creates a new item. To remove one, send it with `_delete: true`; every other field on a _delete item is ignored, including js_code. This is the safe verb for applying generated functions. Run validate_schema with mode 'patch' first.
generate_sheet_jsonGenerate a COMPLETE CSVBox sheet (title, sheet_columns, destinations, webhooks, security_settings, steps) from a natural-language prompt using a configured LLM. Does NOT call the CSVBox API. Returns { sheet, source, validation }. Requires ANTHROPIC_API_KEY or OPENAI_API_KEY; without one it returns an error pointing to the create_csvbox_sheet MCP prompt. Input: { prompt }.
create_importer_from_promptGenerate a COMPLETE CSVBox sheet from a natural-language prompt via a configured LLM, validate it locally, then create it via POST /1.1/sheet. Returns { generated_schema, source, validation, api_response }. Aborts (no API call) if no LLM provider is configured or if validation fails. Requires ANTHROPIC_API_KEY or OPENAI_API_KEY plus CSVBox credentials.
generate_import_codeGenerate complete CSVBox importer integration code for a framework (vanilla-js, react, vuejs2 [Vue 2], vuejs3 [Vue 3], angular [Angular 8-13], angular2 [Angular 14+]). Input: { framework }. Replace the license key placeholder with your sheet's license key.
generate_sheet_functionsAuthor CSVBox virtual_columns, validation_functions, and data_transforms from a natural-language prompt using a configured LLM. Does NOT call the CSVBox API — it returns JSON so you can REVIEW the generated JavaScript before applying it with patch_sheet. Collections the request does not imply are omitted, never returned as empty arrays. Returns { virtual_columns?, validation_functions?, data_transforms?, source, validation }. Requires ANTHROPIC_API_KEY or OPENAI_API_KEY; without one it returns an error pointing to the csvbox_sheet_functions MCP prompt. Input: { prompt, sheet? }.
validate_schemaValidate a CSVBox sheet schema locally (no API call). Requires a non-empty title; sheet_columns is optional (absent passes, empty yields a warning). When columns are present, checks for missing column_name/display_label/type, unsupported types, duplicate names, duplicate positions, and invalid dependent column references. Also checks virtual_columns, validation_functions, and data_transforms: per-sheet caps, duplicate and colliding names, missing or oversized js_code, scope/run_at enums, column references against sheet_columns, and dependency URLs (https, allowed CDN hosts, .js/.mjs, integrity digest). Pass mode ('create' | 'put' | 'patch', default 'create') so empty-array and _delete rules match the verb you are about to use. Returns { valid, errors, warnings }.
submit_fileSubmit a file for import via POST /1.1/file. Provide exactly one of public_file_url (JSON submission) or file_base64 + file_name (multipart direct upload — file_base64 is decoded server-side and sent to CSVBox as true binary multipart content, never as a base64 string). Input: { sheet_license_key, public_file_url? | (file_base64?, file_name?), file_sheet_name?, user?, options?, dynamic_columns? }. Returns the API response.
| create_sheet | Create a new CSVBox sheet via POST /1.1/sheet. Input: { sheet }. Returns the API response. | |
| update_sheet | Replace an existing CSVBox sheet via PUT /1.1/sheet/{sheet_license_key}. Input: { sheet_license_key, sheet }. Returns the API response. DESTRUCTIVE: PUT is authoritative for every collection it sends — items listed are created or updated in place, and any existing item the array does not name is DELETED. This applies to virtual_columns, validation_functions and data_transforms: sending an empty array DELETES ALL of that collection's items, while OMITTING the key leaves them untouched. `_delete` is not valid here; use patch_sheet to remove a single item. Run validate_schema with mode 'put' first to catch a destructive body. | |
| patch_sheet | Partially update a CSVBox sheet via PATCH /1.1/sheet/{sheet_license_key}. Sends only the changes object. Input: { sheet_license_key, changes }. Returns the API response. PATCH MERGES: only the items you list are touched and nothing is deleted implicitly, so an empty array is a no-op. Items in virtual_columns, validation_functions and data_transforms are matched by column_name / function_name / transform_name respectively — an unmatched name creates a new item. To remove one, send it with `_delete: true`; every other field on a _delete item is ignored, including js_code. This is the safe verb for applying generated functions. Run validate_schema with mode 'patch' first. | |
| generate_sheet_json | Generate a COMPLETE CSVBox sheet (title, sheet_columns, destinations, webhooks, security_settings, steps) from a natural-language prompt using a configured LLM. Does NOT call the CSVBox API. Returns { sheet, source, validation }. Requires ANTHROPIC_API_KEY or OPENAI_API_KEY; without one it returns an error pointing to the create_csvbox_sheet MCP prompt. Input: { prompt }. | |
| create_importer_from_prompt | Generate a COMPLETE CSVBox sheet from a natural-language prompt via a configured LLM, validate it locally, then create it via POST /1.1/sheet. Returns { generated_schema, source, validation, api_response }. Aborts (no API call) if no LLM provider is configured or if validation fails. Requires ANTHROPIC_API_KEY or OPENAI_API_KEY plus CSVBox credentials. | |
| generate_import_code | Generate complete CSVBox importer integration code for a framework (vanilla-js, react, vuejs2 [Vue 2], vuejs3 [Vue 3], angular [Angular 8-13], angular2 [Angular 14+]). Input: { framework }. Replace the license key placeholder with your sheet's license key. | |
| generate_sheet_functions | Author CSVBox virtual_columns, validation_functions, and data_transforms from a natural-language prompt using a configured LLM. Does NOT call the CSVBox API — it returns JSON so you can REVIEW the generated JavaScript before applying it with patch_sheet. Collections the request does not imply are omitted, never returned as empty arrays. Returns { virtual_columns?, validation_functions?, data_transforms?, source, validation }. Requires ANTHROPIC_API_KEY or OPENAI_API_KEY; without one it returns an error pointing to the csvbox_sheet_functions MCP prompt. Input: { prompt, sheet? }. | |
| validate_schema | Validate a CSVBox sheet schema locally (no API call). Requires a non-empty title; sheet_columns is optional (absent passes, empty yields a warning). When columns are present, checks for missing column_name/display_label/type, unsupported types, duplicate names, duplicate positions, and invalid dependent column references. Also checks virtual_columns, validation_functions, and data_transforms: per-sheet caps, duplicate and colliding names, missing or oversized js_code, scope/run_at enums, column references against sheet_columns, and dependency URLs (https, allowed CDN hosts, .js/.mjs, integrity digest). Pass mode ('create' | 'put' | 'patch', default 'create') so empty-array and _delete rules match the verb you are about to use. Returns { valid, errors, warnings }. | |
| submit_file | Submit a file for import via POST /1.1/file. Provide exactly one of public_file_url (JSON submission) or file_base64 + file_name (multipart direct upload — file_base64 is decoded server-side and sent to CSVBox as true binary multipart content, never as a base64 string). Input: { sheet_license_key, public_file_url? | (file_base64?, file_name?), file_sheet_name?, user?, options?, dynamic_columns? }. Returns the API response. |
Configuration
CSVBOX_API_KEYRequiredSecretCSVBox API key
CSVBOX_API_SECRETRequiredSecretCSVBox API secret
ANTHROPIC_API_KEYSecretAnthropic API key for AI-powered tools
OPENAI_API_KEYSecretOpenAI API key for AI-powered tools
| Name | Description | |
|---|---|---|
| CSVBOX_API_KEY | CSVBox API key | RequiredSecret |
| CSVBOX_API_SECRET | CSVBox API secret | RequiredSecret |
| ANTHROPIC_API_KEY | Anthropic API key for AI-powered tools | Secret |
| OPENAI_API_KEY | OpenAI API key for AI-powered tools | Secret |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubcsvbox-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
| Tool | Purpose | API call |
|---|---|---|
create_sheet |
Create a CSVBox sheet | POST /1.1/sheet |
update_sheet |
Replace an existing sheet | PUT /1.1/sheet/{key} |
patch_sheet |
Partially update a sheet | PATCH /1.1/sheet/{key} |
generate_sheet_json |
NL prompt → complete sheet JSON (via LLM) | none (calls LLM) |
create_importer_from_prompt |
NL prompt → validate → create | POST /1.1/sheet (+ LLM) |
generate_import_code |
Integration code (vanilla-js/react/vue/angular) | none |
generate_sheet_functions |
NL prompt → virtual columns / validation functions / data transforms (via LLM) | none (calls LLM) |
validate_schema |
Local schema validation | none |
CSVBox currently has no GET or LIST endpoints, so there are intentionally no
get_sheet/list_sheettools.
It also exposes two MCP prompts:
| Prompt | Purpose |
|---|---|
create_csvbox_sheet |
Make the host client's own LLM build a complete CSVBox sheet (no server-side LLM key needed). |
csvbox_sheet_functions |
Make the host client's own LLM author virtual columns, validation functions, and data transforms (no server-side LLM key needed). |
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:
- Server LLM — when
ANTHROPIC_API_KEYorOPENAI_API_KEYis set, the server calls the LLM directly. Works in MCP Inspector and headless. - 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 callvalidate_schemaandcreate_sheet. Free. - None configured —
generate_sheet_jsonreturns a structured "no LLM provider configured" error pointing to the MCP prompt, andcreate_importer_from_promptdoes 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 everycolumn_nameis globally unique.
Data types and validations are inferred from the field names and any requested types:
| Requested / implied | Column type |
Validators |
|---|---|---|
| Dropdown / status / category with fixed options | list |
values: [...] candidate options |
| Percentage / percent | number |
min_value: 0, max_value: 100 |
| Positive numeric (quantity, count, stock, cost, age) | number |
min_value: 0 |
| ID / code / reference number | text |
— |
email |
— | |
| Phone / mobile | phone_number |
— |
| URL / website | url |
— |
| Price / cost / amount / salary | currency |
— |
| Date fields | date |
format: "YYYY-MM-DD" |
| Boolean / is_* / active | boolean |
— |
| GST / GSTIN / tax id | regex |
GSTIN pattern |
| PIN code / postal code (India) | regex |
^[1-9][0-9]{5}$ |
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 viaLLM_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 flaggedTRUNCATED(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:
| Collection | Identified by | Max | js_code must… |
|---|---|---|---|
virtual_columns |
column_name |
20 | return the computed cell value |
validation_functions |
function_name |
10 | return an array of error strings ([] = valid) |
data_transforms |
transform_name |
10 | mutate the csvbox object and return it |
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
update_sheet (PUT) |
patch_sheet (PATCH) |
|
|---|---|---|
| Collection you send | authoritative — any existing item not named is deleted | merged — unnamed items are left alone |
"virtual_columns": [] |
deletes all 20 | no-op |
| Key omitted | untouched | untouched |
_delete: true |
not valid | removes that item (all its other fields ignored) |
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 anintegritydigest can change under your customers at any time;validate_schemawarns 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-keyandx-csvbox-secret-api-key(matching the CSVBox reference payloads). These are defined as constants insrc/services/csvbox-api.tsif 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.
These are always sent — there is no environment variable or tool input that disables or changes them. They carry no credentials and nothing derived from your tool inputs. Tools that make no API call (generate_sheet_json, generate_sheet_functions, generate_import_code, validate_schema) send no request and therefore no headers.
LLM provider (for prompt → sheet generation)
generate_sheet_json and create_importer_from_prompt need an LLM. Set one of:
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
The provider is auto-detected:
| Condition | Provider | Default model |
|---|---|---|
LLM_PROVIDER=anthropic (and its key set) |
Anthropic | claude-haiku-4-5 |
LLM_PROVIDER=openai (and its key set) |
OpenAI | gpt-4o-mini |
ANTHROPIC_API_KEY set (no LLM_PROVIDER) |
Anthropic | claude-haiku-4-5 |
OPENAI_API_KEY set (no LLM_PROVIDER) |
OpenAI | gpt-4o-mini |
| neither key set | none — tools return an error pointing to the create_csvbox_sheet MCP prompt |
— |
LLM_PROVIDER disambiguates when both keys are present; LLM_MODEL overrides the model for whichever provider is chosen. For large category/module schemas (100+ columns) set LLM_MODEL to a stronger model (e.g. claude-sonnet-4-6) — see Category / module expansion.
MCP Inspector: set the LLM key in the Inspector's environment-variables panel to use the server-LLM path. Inspector has no host LLM of its own, so it can render the
create_csvbox_sheetprompt but cannot execute it — for the keyless path use a client with a model (Cursor, Claude Desktop, Cline).
Running locally
# After building:
npm start
# Or run the built file directly:
node dist/index.js
The server speaks MCP over stdio and logs csvbox-mcp-server running on stdio to stderr (stdout is reserved for the protocol).
Client configuration
For a published installation, use the npm package with npx. Set CSVBOX_API_KEY / CSVBOX_API_SECRET in the env block.
Note: The npm package is
@csvbox/mcp-serverand the executable iscsvbox-mcp-server.
Claude Desktop
Add the following to your Claude Desktop MCP configuration:
{
"mcpServers": {
"csvbox": {
"command": "npx",
"args": [
"-y",
"--package=@csvbox/mcp-server",
"csvbox-mcp-server"
],
"env": {
"CSVBOX_API_KEY": "your_api_key",
"CSVBOX_API_SECRET": "your_api_secret"
}
}
}
}
Cursor
Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):
{
"mcpServers": {
"csvbox": {
"command": "npx",
"args": [
"-y",
"--package=@csvbox/mcp-server",
"csvbox-mcp-server"
],
"env": {
"CSVBOX_API_KEY": "your_api_key",
"CSVBOX_API_SECRET": "your_api_secret"
}
}
}
}
Windsurf
Edit ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"csvbox": {
"command": "npx",
"args": [
"-y",
"--package=@csvbox/mcp-server",
"csvbox-mcp-server"
],
"env": {
"CSVBOX_API_KEY": "your_api_key",
"CSVBOX_API_SECRET": "your_api_secret"
}
}
}
}
Roo Code
In the Roo Code MCP settings (mcp_settings.json):
{
"mcpServers": {
"csvbox": {
"command": "npx",
"args": [
"-y",
"--package=@csvbox/mcp-server",
"csvbox-mcp-server"
],
"env": {
"CSVBOX_API_KEY": "your_api_key",
"CSVBOX_API_SECRET": "your_api_secret"
}
}
}
}
Cline
In the Cline MCP settings (cline_mcp_settings.json):
{
"mcpServers": {
"csvbox": {
"command": "npx",
"args": [
"-y",
"--package=@csvbox/mcp-server",
"csvbox-mcp-server"
],
"env": {
"CSVBOX_API_KEY": "your_api_key",
"CSVBOX_API_SECRET": "your_api_secret"
}
}
}
}
VS Code MCP
Add to .vscode/mcp.json (or the global mcp.json):
{
"servers": {
"csvbox": {
"command": "npx",
"args": [
"-y",
"--package=@csvbox/mcp-server",
"csvbox-mcp-server"
],
"env": {
"CSVBOX_API_KEY": "your_api_key",
"CSVBOX_API_SECRET": "your_api_secret"
}
}
}
}
Example tool calls
Generate a complete sheet from a prompt (LLM, no CSVBox API call):
// generate_sheet_json (requires ANTHROPIC_API_KEY or OPENAI_API_KEY)
{ "prompt": "Create employee importer with name, email, salary, joining date; destination as testapi; allow only xlsx files" }
Returns { "sheet": { "title": ..., "sheet_columns": [...], "destinations": [...], "steps": {...} }, "source": "llm:anthropic:claude-haiku-4-5", "validation": { "valid": true, ... } }. Data fields become columns (salary → currency, joining date → date); the destination and xlsx setting go to destinations / steps, not columns. With no LLM key, returns an error pointing to the create_csvbox_sheet prompt.
Validate a schema before sending it:
// validate_schema
{ "sheet": { "title": "Customers", "sheet_columns": [
{ "column_name": "email", "display_label": "Email", "type": "email" }
] } }
Returns { "valid": true, "errors": [], "warnings": [ ... ] }.
Create a sheet:
// create_sheet
{ "sheet": { "title": "Customer Import", "sheet_columns": [
{ "column_name": "name", "display_label": "Name", "type": "text" },
{ "column_name": "email", "display_label": "Email", "type": "email" }
] } }
Generate + create in one step:
// create_importer_from_prompt (requires an LLM key + CSVBox credentials)
{ "prompt": "Create customer importer with name, email, phone; allow for example.com" }
Returns { "generated_schema": { ... }, "source": ..., "validation": { ... }, "api_response": { ... } }. Aborts without calling the API if no LLM provider is configured or the generated schema fails validation.
Replace a sheet:
// update_sheet
{ "sheet_license_key": "abc123", "sheet": { "title": "Updated", "sheet_columns": [ ... ] } }
Destructive for any collection you send — see PUT vs PATCH.
Patch a sheet:
// patch_sheet
{ "sheet_license_key": "abc123", "changes": { "title": "New Title" } }
Remove one function without touching the rest:
// patch_sheet
{ "sheet_license_key": "abc123",
"changes": { "virtual_columns": [ { "column_name": "full_name", "_delete": true } ] } }
Generate integration code:
// generate_import_code
{ "framework": "react" }
Supported column types
text, number, email, date, time, boolean, regex, ip, url, credit_card, phone_number, currency, list, dependent_list, dynamic_list, dependent_dynamic_list, multiselect_list, multiselect_dynamic_list.
Development
npm run build # compile TypeScript → dist/
npm start # run the built server
npm run lint # type-check without emitting
npm test # compile and run the unit suite (alias: npm run test:unit)
Tests
npm test compiles src/tests/ and runs it with Node's built-in test runner — no
test framework, no mocking library.
The suite is hermetic. It never contacts an external host, never reads your
ambient CSVBOX_API_* / ANTHROPIC_API_KEY / OPENAI_API_KEY, and never touches
a real CSVBox account, so it passes identically whether or not you have
credentials configured. HTTP is intercepted at the axios adapter; the LLM is a
scripted fake; the one test that needs real request encoding starts an ephemeral
listener on 127.0.0.1 and closes it afterwards. Tests that read environment
variables set what they need explicitly and restore the previous values.
E2E tests
npm run test:e2e # run the Playwright suite
npm run test:e2e:report # open the HTML report from the last run
Specs live in e2e/, configured by playwright.config.ts. Like the unit suite,
this suite is hermetic: it starts mock CSVBox and LLM servers on loopback
(e2e/support/mock-csvbox-server.ts, e2e/support/mock-llm-server.ts) and
drives the real built server (dist/index.js) through MCP Inspector with
fake credentials pointed at those mocks — it never contacts a real CSVBox
account or LLM provider, and never reads your .env. A separate,
zero-credential Inspector instance covers the "missing credentials" error
paths. Requires npm run build first (the test:e2e webServer entries build
automatically).
Embedding the server
createServer() is exported from the entry module. It registers every tool and
prompt and returns the McpServer without attaching a transport, so you can
connect it to one of your own:
import { createServer } from "@csvbox/mcp-server";
const server = createServer();
await server.connect(myTransport);
Importing the module does not start anything; the stdio server runs only when
dist/index.js is executed directly.
License
MIT
CSVBox MCP questions
How do I add CSVBox MCP to Claude Code?
Run claude mcp add --env 'CSVBOX_API_KEY=<YOUR_CSVBOX_API_KEY>' --env 'CSVBOX_API_SECRET=<YOUR_CSVBOX_API_SECRET>' --env 'ANTHROPIC_API_KEY=<YOUR_ANTHROPIC_API_KEY>' --env 'OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>' csvbox-mcp-server -- npx -y @csvbox/mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add CSVBox MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does CSVBox MCP provide?
It exposes 9 tools, including create_sheet, update_sheet, patch_sheet, generate_sheet_json, create_importer_from_prompt.
Can I list or get existing CSVBox sheets using this server?
No, CSVBox currently has no GET or LIST endpoints, so there are intentionally no get_sheet or list_sheet tools.
How can I generate a CSVBox sheet without providing an LLM API key to the server?
You can use the 'create_csvbox_sheet' MCP prompt, which allows the host client's own LLM to build the sheet for free.
What environment variables are required to use the API-backed tools?
You need to set CSVBOX_API_KEY and CSVBOX_API_SECRET to access the CSVBox API.
Does the server execute the JavaScript code in the sheets?
No, the server treats the JavaScript code as an opaque string and never executes it.