mcp-csv-server

An MCP server that lets an AI assistant preview, query, aggregate, and convert CSV/TSV data — safely, with no API key.

Give Claude (or any MCP client) the ability to actually work with spreadsheets: filter rows, sum/average/group columns, and turn CSV into JSON — instead of eyeballing a pasted table and guessing. Pure TypeScript, dependency-light, and runnable with zero credentials, so a reviewer can try it in one command.

日本語の概要

AIアシスタント（Claude等）に「CSV/業務データを正しく扱う力」を与えるMCPサーバです。表をそのまま 読ませて推測させるのではなく、行の絞り込み・列の集計（合計/平均/最大最小）・グループ集計・JSON変換を ツールとして提供します。APIキー不要で動くので、その場で試せます。

• 壊れにくいCSVパーサ：引用符・エスケープ（""）・引用符内のカンマ/改行に対応（素朴なsplit(',')が壊れる実データを正しく処理）。
• 型付きエラー＋対処ヒント：[UNKNOWN_COLUMN] Unknown column "x". Hint: Available columns: ... のように、AIにも人にも原因と対処が分かる。
• 責務分離：csv/（パース・クエリの純粋ロジック）/ tools/（MCPツール定義）/ server.ts（薄い配線）。
• テスト：パーサ・クエリ・ツールを19本のユニットテストで検証（全エラー経路含む）。CI緑。

Tools

aggregate supports count, sum, avg, min, max; where ops are eq, ne, gt, gte, lt, lte, contains (ANDed together). Numbers tolerate thousands separators ("2,000" → 2000).

Install & run

git clone https://github.com/takuyahoritacromtech/mcp-csv-server.git
cd mcp-csv-server
npm install
npm run build

Use with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "csv": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-csv-server/dist/index.js"]
    }
  }
}

Restart the client; the csv_preview, csv_query, and csv_to_json tools appear.

Quick smoke test (no client needed)

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  | node dist/index.js
# → {"result":{...,"serverInfo":{"name":"mcp-csv-server",...}},"jsonrpc":"2.0","id":1}

Example: "total sales by region"

Given a csv_query call with:

{ "csv": "region,amount\nEast,1000\nWest,2000\nEast,500",
  "groupBy": "region",
  "aggregate": { "fn": "sum", "column": "amount" } }

the tool returns:

{ "columns": ["region", "sum_amount"],
  "rows": [{ "region": "East", "sum_amount": 1500 }, { "region": "West", "sum_amount": 2000 }],
  "rowCount": 2 }

Design notes (the "why")

• A real CSV parser, not `split(',')` — a small RFC 4180 state machine handles quoting,

escaped quotes, and embedded delimiters/newlines. This is where naive tools silently corrupt data.

• Pure core, thin MCP shell — all logic lives in csv/ and tools/ as pure functions, so it

is unit-tested without the protocol. server.ts only maps tools to the SDK and converts CsvError into clean tool errors.

• Typed errors with hints — every failure (UNKNOWN_COLUMN, NON_NUMERIC_COLUMN,

CSV_PARSE_ERROR, …) is actionable from the message alone.

• Validated inputs — every tool input is a Zod schema, so malformed calls are rejected before

any work happens.

Testing

npm run check   # typecheck + lint + test

19 unit tests cover CSV parsing (quoting, TSV, CRLF, ragged rows, empty, unterminated quotes), the query engine (filter/select/aggregate/group/limit + every error code), and the three tools.

License

MIT © Takuya Horita