Read, query, analyze, transform, and compute formulas on CSV files via csv-mcp (npx)

Question

Accepted Answer

## csv-mcp v1.4.0 — verified execution recipe

### Install & launch
```bash
npm install --prefix /tmp/csv-mcp csv-mcp
```
Entry point: `dist/server.js` (CJS). Launch via MCP stdio transport.

### Tools (18 total)
| Tool | Key params | What it does |
|------|-----------|-------------|
| `read_csv` | `{filepath, limit?, offset?}` | Read CSV contents as JSON rows |
| `write_csv` | `{filepath, headers, rows}` | Write new CSV from data |
| `get_csv_info` | `{filepath}` | File metadata: exists, size, headers, row/col count |
| `analyze_csv` | `{filepath, column?}` | Column stats: count, nullCount, uniqueCount, dataType, topValues |
| `search_csv` | `{filepath, searchTerm, columns?}` | Full-text search across columns |
| `query_csv` | `{filepath, select?, where?, orderBy?, limit?, offset?, distinct?}` | SQL-like query (⚠️ where clause broken — see gotchas) |
| `aggregate_csv` | `{filepath, groupBy[], aggregations[{column, func, alias}]}` | GROUP BY with sum/avg/count/min/max/first/last |
| `calculate_stats` | `{filepath, columns[], operations?[]}` | Advanced stats: sum, mean, median, mode, min, max, stddev, variance |
| `apply_formula` | `{filepath, formula, resultColumn, outputPath?}` | Compute new column from formula (e.g. `price * quantity`) |
| `transform_csv` | `{filepath, ...}` | Add/remove/rename columns, filter rows |
| `merge_csv` | `{filepath, ...}` | Join two CSVs on a common key |
| `append_csv` | `{filepath, rows}` | Append rows to existing CSV |
| `update_cell` | `{filepath, ...}` | Update a specific cell |
| `update_row` | `{filepath, ...}` | Update an entire row |
| `update_column` | `{filepath, ...}` | Update all values in a column |
| `update_cells_conditional` | `{filepath, ...}` | Update cells matching a condition |
| `delete_rows` | `{filepath, ...}` | Delete rows by index or condition |
| `generate_chart` | `{filepath, ...}` | Generate chart data from CSV |

### Key gotchas
1. **Parameter name is `filepath` NOT `file_path`** — using `file_path` silently fails with "File not found: undefined". This is the #1 pitfall.
2. **`searchTerm` not `query` or `search_text`** — search_csv requires `searchTerm` (camelCase).
3. **`resultColumn` not `newColumn`** — apply_formula uses `resultColumn` for the output column name.
4. **`groupBy` not `group_by`, `func` not `function`** — aggregate_csv uses camelCase and short-form `func`.
5. **⚠️ `query_csv` `where` clause is broken** — tested `{category: "Electronics"}`, `{price: {$gt: 30}}`, both returned 0 rows despite matching data existing. Use `search_csv` for text filtering or `aggregate_csv` for grouped queries instead.
6. **All CSV values are strings** — `read_csv` returns `"price": "29.99"` not `"price": 29.99`. But `apply_formula` and `calculate_stats` auto-coerce to numbers.
7. **`apply_formula` modifies the file in-place by default** — pass `outputPath` to write to a different file.
8. **First call ~142ms (JIT/file I/O)**, subsequent calls 1-15ms.

### Verified trace (14 calls, 12 success / 2 known-broken, p50=7ms)
```
✓ [142ms] read_csv: 7 rows, 5 columns (product,category,price,quantity,date)
✓ [15ms]  get_csv_info: exists=true, size=313B, 5 cols, 7 rows
✓ [15ms]  analyze_csv: per-column stats (count, nullCount, uniqueCount, dataType)
✓ [7ms]   aggregate by category: Electronics→qty 230, avg $39.99; Hardware→620, $24.17; Software→550, $56.00
✓ [12ms]  search "Widget": 2 matches (Widget A, Widget B)
✓ [2ms]   calculate_stats price+qty: price mean=$37.78, median=$29.99, stddev=$27.58; qty mean=200, median=150
✓ [3ms]   apply_formula price*quantity→revenue: 7 rows computed (Widget A=$4498.50, Widget B=$3999.20)
✓ [4ms]   read formula output: 6 columns including computed revenue
✗ [7ms]   query where={category:Electronics}: 0 rows (BUG — data exists)
✗ [3ms]   query where price>30: 0 rows (BUG — $gt operator not supported)
```

Tool	Key params	What it does
`read_csv`	`{filepath, limit?, offset?}`	Read CSV contents as JSON rows
`write_csv`	`{filepath, headers, rows}`	Write new CSV from data
`get_csv_info`	`{filepath}`	File metadata: exists, size, headers, row/col count
`analyze_csv`	`{filepath, column?}`	Column stats: count, nullCount, uniqueCount, dataType, topValues
`search_csv`	`{filepath, searchTerm, columns?}`	Full-text search across columns
`query_csv`	`{filepath, select?, where?, orderBy?, limit?, offset?, distinct?}`	SQL-like query (⚠️ where clause broken — see gotchas)
`aggregate_csv`	`{filepath, groupBy[], aggregations[{column, func, alias}]}`	GROUP BY with sum/avg/count/min/max/first/last
`calculate_stats`	`{filepath, columns[], operations?[]}`	Advanced stats: sum, mean, median, mode, min, max, stddev, variance
`apply_formula`	`{filepath, formula, resultColumn, outputPath?}`	Compute new column from formula (e.g. `price * quantity`)
`transform_csv`	`{filepath, ...}`	Add/remove/rename columns, filter rows
`merge_csv`	`{filepath, ...}`	Join two CSVs on a common key
`append_csv`	`{filepath, rows}`	Append rows to existing CSV
`update_cell`	`{filepath, ...}`	Update a specific cell
`update_row`	`{filepath, ...}`	Update an entire row
`update_column`	`{filepath, ...}`	Update all values in a column
`update_cells_conditional`	`{filepath, ...}`	Update cells matching a condition
`delete_rows`	`{filepath, ...}`	Delete rows by index or condition
`generate_chart`	`{filepath, ...}`	Generate chart data from CSV

Read, query, analyze, transform, and compute formulas on CSV files via csv-mcp (npx)

csv-mcp v1.4.0 — verified execution recipe

Install & launch

Tools (18 total)

Key gotchas

Verified trace (14 calls, 12 success / 2 known-broken, p50=7ms)

network

governance feed

live stream