CSV and Filesystem MCP

Stdio MCP servers for safely working with CSV/TSV files and general UTF-8 text files.

Run

uv sync
CSV_MCP_ROOT=/absolute/path/to/csv-workspace uv run csv-mcp
FILESYSTEM_MCP_ROOT=/absolute/path/to/workspace uv run filesystem-mcp

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

LangChain agent

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-agent

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

Tools

Tool	Purpose
`list_csv_files`	List available CSV/TSV files recursively
`inspect_csv`	Detect encoding/delimiter and report structure, samples, inferred types, and warnings
`preview_csv`	Read a bounded page and optional columns
`read_csv`	Backward-compatible alias for `preview_csv`
`query_csv`	Select, filter, and sort with controlled operators
`summarize_csv`	Group and aggregate with whitelisted functions
`validate_csv`	Check schemas, types, required values, uniqueness, categories, and malformed rows
`compare_csv`	Compare two files by unique key columns
`create_csv`	Create validated atomic output
`append_rows`	Append rows to a new output by default
`update_rows`	Preview or write filtered changes
`delete_rows`	Preview or write filtered deletions
`clean_csv`	Trim, change case, and deduplicate
`merge_csv`	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.

Parsing options

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.

Safe writes

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.

Resources

csv://files
csv://file/{name}/metadata
csv://file/{name}/schema
csv://file/{name}/preview

Limits

Limits are configurable with environment variables:

Variable	Default
`CSV_MCP_MAX_FILE_SIZE`	50 MiB
`CSV_MCP_MAX_ROWS`	1,000,000
`CSV_MCP_MAX_COLUMNS`	500
`CSV_MCP_MAX_FIELD_LENGTH`	1 MiB
`CSV_MCP_MAX_RETURNED_ROWS`	1,000
`CSV_MCP_MAX_FILES`	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.

Test

uv run pytest

csv-mcp