CSV Editor - AI-Powered CSV Processing via MCP

Stateful CSV editing for AI assistants. CSV Editor is an MCP server that gives Claude, ChatGPT, Cursor, Windsurf, and other MCP clients a full suite of CSV operations — with sessions, undo/redo, and auto-save built in. Most data MCPs are analyze-only; this one lets the AI edit.

🆕 What's new in v2.0.0 (April 2026)

• FastMCP 3.x — migrated from FastMCP 2 to 3.2, aligning with MCP spec 2025-11-25.
• Python 3.11+ required (was 3.10+). Tested against 3.11 / 3.12 / 3.13 / 3.14.
• --transport sse removed. Use --transport http (Streamable HTTP) for remote deployments. SSE was deprecated by FastMCP 3.
• Dependency refresh: pydantic 2.13, pyarrow 23, httpx 0.28.
• New CSVEDITORCSVHISTORYDIR env var for configuring the history directory.
• First-class CI test matrix on GitHub Actions.

🎯 Why CSV Editor?

The Problem

The Solution

• Clean messy datasets in seconds
• Perform complex statistical analysis
• Validate data quality automatically
• Transform data with natural language commands
• Track all changes with undo/redo capabilities

Key differentiators vs. other CSV / tabular MCPs

| Capability | CSV Editor | DuckDB / Polars MCPs | Most pandas-based MCPs | |---|---|---|---| | Stateful editing (load → mutate → save) | ✅ | Read-only or single-shot | Partial | | Undo / redo with snapshots | ✅ | ❌ | ❌ | | Multi-session isolation | ✅ | Limited | Limited | | Auto-save with strategies | ✅ (overwrite / backup / versioned / custom) | ❌ | ❌ | | Quality scoring & validation | ✅ | SQL-only | Via separate tools | | File-size sweet spot | <1 GB (pandas) | 50 GB+ (streaming SQL) | Small–medium | | Best for | Edit-and-review workflows | Large-file analytics | Quick analysis |

When to pick CSV Editor: you want the AI to make changes to a CSV and iterate, not just answer questions about it. If your workload is read-only analytics on multi-GB files, a DuckDB-based MCP is likely a better fit; CSV Editor's DuckDB/Polars engine support is tracked on the roadmap.

⚡ Quick Demo

# Your AI assistant can now do this:
"Load the sales data and remove duplicates"
"Filter for Q4 2024 transactions over $10,000"  
"Calculate correlation between price and quantity"
"Fill missing values with the median"
"Export as Excel with the analysis"
All with automatic history tracking and undo capability!

🚀 Quick Start (2 minutes)

Installing via Smithery

To install csv-editor for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @santoshray02/csv-editor --client claude

Fastest Installation (Recommended)

# Install uv if needed (one-time setup)
curl -LsSf https://astral.sh/uv/install.sh | sh
Clone and run
git clone https://github.com/santoshray02/csv-editor.git
cd csv-editor
uv sync
uv run csv-editor

Configure Your AI Assistant

{
  "mcpServers": {
    "csv-editor": {
      "command": "uv",
      "args": ["tool", "run", "csv-editor"],
      "env": {
        "CSVMAXFILE_SIZE": "1073741824"
      }
    }
  }
}

💡 Real-World Use Cases

📊 Data Analyst Workflow

# Morning: Load yesterday's data
session = loadcsv("dailysales.csv")
Clean: Remove duplicates and fix types
removeduplicates(sessionid)
changecolumntype("date", "datetime")
fillmissingvalues(strategy="median", columns=["revenue"])
Analyze: Get insights
get_statistics(columns=["revenue", "quantity"])
detect_outliers(method="iqr", threshold=1.5)
getcorrelationmatrix(min_correlation=0.5)
Report: Export cleaned data
exportcsv(format="excel", filepath="clean_sales.xlsx")

🏭 ETL Pipeline

# Extract from multiple sources
loadcsvfrom_url("https://api.example.com/data.csv")
Transform with complex operations
filter_rows(conditions=[
    {"column": "status", "operator": "==", "value": "active"},
    {"column": "amount", "operator": ">", "value": 1000}
])
add_column(name="quarter", formula="Q{(month-1)//3 + 1}")
groupbyaggregate(group_by=["quarter"], aggregations={
    "amount": ["sum", "mean"],
    "customer_id": "count"
})
Load to different formats
export_csv(format="parquet")  # For data warehouse
export_csv(format="json")     # For API

🔍 Data Quality Assurance

# Validate incoming data
validate_schema(schema={
    "customer_id": {"type": "integer", "required": True},
    "email": {"type": "string", "pattern": r"^[^@]+@[^@]+\.[^@]+$"},
    "age": {"type": "integer", "min": 0, "max": 120}
})
Quality scoring
qualityreport = checkdata_quality()
Returns: overallscore, missingdata%, duplicates, outliers
Anomaly detection
anomalies = find_anomalies(methods=["statistical", "pattern"])

🎨 Core Features

Data Operations

• Load & Export: CSV, JSON, Excel, Parquet, HTML, Markdown
• Transform: Filter, sort, group, pivot, join
• Clean: Remove duplicates, handle missing values, fix types
• Calculate: Add computed columns, aggregations

Analysis Tools

• Statistics: Descriptive stats, correlations, distributions
• Outliers: IQR, Z-score, custom thresholds
• Profiling: Complete data quality reports
• Validation: Schema checking, quality scoring

Productivity Features

• Auto-Save: Never lose work with configurable strategies
• History: Full undo/redo with operation tracking
• Sessions: Multi-user support with isolation
• Performance: Stream processing for large files

📚 Available Tools

⚙️ Configuration

Environment variables

| Variable | Default | Description | |---|---|---| | CSVMAXFILE_SIZE | 1024 (MB) | Maximum file size (megabytes) | | CSVSESSIONTIMEOUT | 60 (minutes) | Session timeout | | CSVEDITORCSVHISTORYDIR | .csv_history | Directory for persisted operation history |

Auto-Save Strategies

CSV Editor automatically saves your work with configurable strategies:

• Overwrite (default) - Update original file
• Backup - Create timestamped backups
• Versioned - Maintain version history
• Custom - Save to specified location

# Configure auto-save
configureautosave(
    strategy="backup",
    backup_dir="/backups",
    max_backups=10
)

🛠️ Advanced Installation Options

git clone https://github.com/santoshray02/csv-editor.git
cd csv-editor
pip install -e .

pipx install git+https://github.com/santoshray02/csv-editor.git

pip install csv-editor            # latest
pip install csv-editor==2.0.0     # pinned
Or with uv:
uv tool install csv-editor

# Latest main
pip install git+https://github.com/santoshray02/csv-editor.git
Specific release
pip install git+https://github.com/santoshray02/csv-editor.git@v2.0.0
Or with uv
uv pip install git+https://github.com/santoshray02/csv-editor.git@v2.0.0

🧪 Development

Running tests

uv run pytest tests/ -v                  # Run tests
uv run pytest tests/ --cov=src/csv_editor # With coverage
uv run ruff check src/ tests/             # Lint
uv run black --check src/ tests/          # Format check
uv run mypy src/                          # Type check

CI runs the full pytest matrix on Python 3.11–3.14 for every push to main — see .github/workflows/test.yml.

Project Structure

csv-editor/
├── src/csv_editor/   # Core implementation
│   ├── tools/        # MCP tool implementations
│   ├── models/       # Data models
│   └── server.py     # MCP server
├── tests/            # Test suite
├── examples/         # Usage examples
└── docs/            # Documentation

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick Contribution Guide

• Fork the repository
• Create a feature branch
• Make your changes with tests
• Run uv run pytest tests/ and uv run ruff check src/ tests/
• Submit a pull request

📈 Roadmap

Post-v2.0.0 priorities (see the 2026 relevance audit for context):

• [ ] pandas 3.0 / numpy 2.4 — Copy-on-Write migration, Arrow-backed default strings (follow-up to v2.0.0).
• [ ] DuckDB + Polars engines — swappable backends with DuckDB as the default for files >100 MB (closes the large-file gap).
• [ ] MCP async Tasks + Resource Links — non-blocking loadcsv / exportcsv / profile_data for GB files; paginated large results.
• [ ] Remote HTTP + OAuth (CIMD) — enables ChatGPT Connectors and VS Code Copilot remote usage.
• [ ] Elicitation — prompt for ambiguous CSV dialect / encoding / dtype at load time instead of failing.
• [ ] Docs migration — Docusaurus → MkDocs-Material with mkdocstrings for auto-generated API docs.

💬 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

📄 License

MIT License - see LICENSE file

🙏 Acknowledgments

Built with:

• FastMCP - Fast Model Context Protocol
• Pandas - Data manipulation
• NumPy - Numerical computing

Ready to supercharge your AI's data capabilities? Get started in 2 minutes →