# CSVBox MCP server

> Manage CSVBox importer sheets by creating, updating, validating, and generating schemas using natural language prompts.

- Repository: https://github.com/csvbox-io/csvbox-mcp-server
- Page: https://hostedmcp.org/servers/csvbox-io/csvbox-mcp-server
- Transport: stdio
- Stars: 1
- License: MIT
- Latest version: 1.0.1

## Install

### Claude Code

```sh
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
```

### Cursor (`~/.cursor/mcp.json`)

```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>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```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>"
      }
    }
  }
}
```

### VS Code CLI

```sh
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>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```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>"
      }
    }
  }
}
```

### Codex

```sh
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-server
```

### Codex config.toml (`~/.codex/config.toml`)

```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>"
```

### Gemini CLI

```sh
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-server
```

### Gemini settings.json (`~/.gemini/settings.json`)

```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>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `CSVBOX_API_KEY` | yes | yes | CSVBox API key |
| `CSVBOX_API_SECRET` | yes | yes | CSVBox API secret |
| `ANTHROPIC_API_KEY` | no | yes | Anthropic API key for AI-powered tools |
| `OPENAI_API_KEY` | no | yes | OpenAI API key for AI-powered tools |

## Tools (9)

- `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.

## FAQ

### 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.
