The csv-mcp server provides a comprehensive set of tools for safely reading, analyzing, validating, and transforming CSV/TSV files within a sandboxed workspace directory. It offers the following capabilities:
List files (list_csv_files): Recursively discover all CSV and TSV files in the workspace.
Inspect (inspect_csv): Auto-detect encoding, delimiter, headers, column types, and preview sample rows; report malformed rows.
Preview/Read (preview_csv/read_csv): Read a bounded slice of rows with optional column selection, offset, and limit.
Query (query_csv): Filter rows using operators (e.g., =, !=, >, contains, is_null, in), select columns, and sort results.
Summarize (summarize_csv): Group by columns and compute aggregations (count, sum, mean, min, max, median, unique_count).
Validate (validate_csv): Check schemas, data types, required fields, uniqueness, allowed values, and row structure.
Compare (compare_csv): Diff two CSV files by key columns to find added, removed, or changed rows.
Create (create_csv): Atomically create new CSV/TSV files with validated rows, column types, and formula injection protection.
Append (append_rows): Add validated rows to an existing file, with optional new output file.
Update (update_rows): Modify rows matching filters, with dry-run preview and output file support.
Delete (delete_rows): Remove rows matching filters, with dry-run option and mandatory non-empty filter.
Clean (clean_csv): Trim whitespace, change case (upper/lower), and deduplicate rows on selected columns.
Merge (merge_csv): Concatenate multiple files or join two files on keys (inner, left, right, outer).
Custom Parsing: Control encoding, delimiter, quote character, decimal separator, null handling, column names/types, and date formats.
Safety and configuration features: All operations are restricted to a configured root directory, with path traversal and symlink protections; writes use atomic transactions with temporary files and SHA-256 verification; formula injection protection modes (escape, reject, preserve); configurable limits for file size, rows, columns, field length, and returned rows.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@csv-mcp list CSV files in the workspace"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Stdio MCP servers for safely working with CSV/TSV files and general UTF-8 text files.
uv sync
CSV_MCP_ROOT=/absolute/path/to/csv-workspace uv run csv-mcp
FILESYSTEM_MCP_ROOT=/absolute/path/to/workspace uv run filesystem-mcpMCP client configuration:
{
"mcpServers": {
"csv": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/csv-mcp", "run", "csv-mcp"],
"env": {"CSV_MCP_ROOT": "/absolute/path/to/csv-workspace"}
},
"filesystem": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/csv-mcp", "run", "filesystem-mcp"],
"env": {"FILESYSTEM_MCP_ROOT": "/absolute/path/to/workspace"}
}
}
}Related MCP server: Files MCP Server
Set an OpenAI API key and point the agent at the CSV workspace:
export OPENAI_API_KEY=your-key
export CSV_MCP_ROOT=/absolute/path/to/csv-workspace
export FILESYSTEM_MCP_ROOT=/absolute/path/to/workspace
uv run csv-agentThis starts an interactive chat; use /quit to exit. For a single request:
uv run csv-agent "List the CSV files and summarize the sales data"The agent loads both MCP servers. If FILESYSTEM_MCP_ROOT is unset, it uses
CSV_MCP_ROOT so both toolsets operate on the same workspace.
The default model is openai:gpt-4o-mini. Override it with CSV_AGENT_MODEL, using a
LangChain provider:model identifier whose provider integration is installed.
A useful workspace layout is:
csv-workspace/
├── input/
├── output/
├── temporary/
└── backups/All paths are resolved below CSV_MCP_ROOT. Absolute paths, traversal, symlink escapes, URLs, and extensions other than .csv/.tsv are rejected.
Tool | Purpose |
| List available CSV/TSV files recursively |
| Detect encoding/delimiter and report structure, samples, inferred types, and warnings |
| Read a bounded page and optional columns |
| Backward-compatible alias for |
| Select, filter, and sort with controlled operators |
| Group and aggregate with whitelisted functions |
| Check schemas, types, required values, uniqueness, categories, and malformed rows |
| Compare two files by unique key columns |
| Create validated atomic output |
| Append rows to a new output by default |
| Preview or write filtered changes |
| Preview or write filtered deletions |
| Trim, change case, and deduplicate |
| Concatenate matching files or join two files |
Filesystem tools are list_directory, read_text_file, write_text_file, and
replace_text. Writes are atomic, refuse existing files by default, create parent
directories, and cannot escape FILESYSTEM_MCP_ROOT through traversal or symlinks.
Query operators are =, !=, >, >=, <, <=, contains, starts_with, ends_with, is_null, not_null, and in. Aggregations are count, sum, mean, minimum, maximum, median, and unique_count.
Tools accept an optional options object:
{
"encoding": "windows-1252",
"delimiter": ";",
"decimal_separator": ",",
"quotechar": "\"",
"escapechar": "\\",
"doublequote": true,
"header_mode": "first_row",
"null_values": ["", "NULL", "N/A"],
"keep_empty_strings": false,
"column_types": {"amount": "decimal"},
"date_formats": {"created_at": "%Y-%m-%d"}
}Supported encodings are UTF-8, UTF-8 with BOM, UTF-16, Latin-1, and Windows-1252. Supported delimiters are comma, semicolon, tab, and pipe. With header_mode: "none", pass column_names or generated names such as column_1 are used.
Append, update, delete, and clean produce a file below output/ unless output_file is supplied. Update and delete default to dry_run: true. Existing destinations require overwrite: true.
Writes:
Validate columns, rows, paths, and formula policy.
Serialize mutations inside the server process.
Write a temporary file beside the destination.
Parse and validate the temporary file.
Calculate SHA-256.
Atomically replace the destination.
spreadsheet_formula_policy accepts escape (default), reject, or preserve. Negative values are preserved only for columns explicitly typed as integer or decimal.
csv://files
csv://file/{name}/metadata
csv://file/{name}/schema
csv://file/{name}/previewLimits are configurable with environment variables:
Variable | Default |
| 50 MiB |
| 1,000,000 |
| 500 |
| 1 MiB |
| 1,000 |
| 10,000 |
The bounded in-memory engine is intentional for this version. Use chunked pandas, PyArrow, DuckDB, or Parquet when files must exceed these limits.
uv run pytestAppend validated rows to a new output file by default.
Inputs: path (required), rows (required), dry_run, options, +4 more. Returns: object
Trim, change case, and deduplicate selected columns.
Inputs: path (required), operations (required), dry_run, options, +4 more. Returns: object
Compare two CSV files by unique key columns.
Inputs: left_path (required), right_path (required), key_columns (required), options, +1 more. Returns: object
Create a CSV/TSV file with atomic output and formula-injection handling.
Inputs: columns (required), output_file (required), rows, options, +3 more. Returns: object
Delete filtered rows, requiring a non-empty filter and defaulting to dry-run.
Inputs: path (required), match (required), dry_run, options, +4 more. Returns: object
Inspect encoding, dialect, columns, types, malformed rows, and samples.
Inputs: path (required), options, sample_rows. Returns: object
List CSV and TSV files below CSV_MCP_ROOT.
Inputs: no named parameters. Returns: result
Concatenate matching files or join exactly two files by keys.
Inputs: mode (required), files (required), output_file (required), options, +6 more. Returns: object
Read a bounded page and optional subset of columns.
Inputs: path (required), limit, offset, columns, +1 more. Returns: object
Select, filter, and sort rows with controlled operators.
Inputs: path (required), sort, limit, select, +2 more. Returns: object
Backward-compatible alias for preview_csv.
Inputs: path (required), limit, offset, columns, +1 more. Returns: object
Group and aggregate with a fixed set of functions.
Inputs: path (required), aggregations (required), options, group_by. Returns: object
Update filtered rows, returning a bounded change preview before optional output.
Inputs: set (required), path (required), match (required), dry_run, +5 more. Returns: object
Validate columns, row widths, types, required values, uniqueness, and categories.
Inputs: path (required), schema (required), options, issue_limit. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 14 tools
Each tool has a distinct purpose: listing, inspecting, previewing, querying, summarizing, validating, comparing, creating, appending, updating, deleting, cleaning, and merging CSV files. The only potential overlap is preview_csv and read_csv, but the description clarifies read_csv is a backward-compatible alias.
All tools follow a consistent verb_noun pattern in snake_case (e.g., list_csv_files, inspect_csv, query_csv). No mixed conventions or irregular naming.
14 tools is well within the ideal 3-15 range for a focused domain. Each tool addresses a specific CSV operation without redundancy, except the alias read_csv which is minimal.
Covers full CRUD lifecycle (create, read, query, update, delete) plus validation, comparison, cleaning, merging, and appending. Only minor gaps like renaming columns or exporting to other formats, but core CSV tasks are well-covered.
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
Remote MCP: JSON repair, JSON Schema validation, JSON to TypeScript, CSV to JSON and JSON to CSV.
MCP server for StyleKit styles, tokens, recipes, lint and repair over stdio or HTTP.