Csv Editor

CSV Editor - AI-Powered CSV Processing via MCP

[](https://www.python.org/) [](https://modelcontextprotocol.io/) [](LICENSE) [](https://github.com/jlowin/fastmcp) [](https://pandas.pydata.org/) [](https://smithery.ai/server/@santoshray02/csv-editor)

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 CSV_EDITOR_CSV_HISTORY_DIR env var for configuring the history directory.
• First-class CI test matrix on GitHub Actions.

Users who pinned `csv-editor>=1, Claude Desktop (click to expand)

Add to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

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

Claude Code, Cursor, Windsurf, VS Code Copilot, Cline, Continue, Zed

Any MCP-capable client works with stdio transport. See [MCPCONFIG.md](MCPCONFIG.md) for per-client setup.

ChatGPT Connectors (remote HTTP)

ChatGPT Connectors require remote Streamable HTTP with OAuth, which is tracked on the [roadmap](#-roadmap) but not yet in v2.0.0. Use stdio-based clients (Claude Desktop, Claude Code, Cursor, etc.) in the meantime.

💡 Real-World Use Cases

📊 Data Analyst Workflow

# Morning: Load yesterday's data
session = load_csv("daily_sales.csv")

# Clean: Remove duplicates and fix types
remove_duplicates(session_id)
change_column_type("date", "datetime")
fill_missing_values(strategy="median", columns=["revenue"])

# Analyze: Get insights
get_statistics(columns=["revenue", "quantity"])
detect_outliers(method="iqr", threshold=1.5)
get_correlation_matrix(min_correlation=0.5)

# Report: Export cleaned data
export_csv(format="excel", file_path="clean_sales.xlsx")

🏭 ETL Pipeline

# Extract from multiple sources
load_csv_from_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}")
group_by_aggregate(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
quality_report = check_data_quality()
# Returns: overall_score, missing_data%, 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

Complete tool list (39 tools)

Server info (2)

• health_check — health status + active session count
• get_server_info — capabilities, supported formats, limits

I/O operations (7)

• load_csv — Load from file
• load_csv_from_url — Load from URL
• load_csv_from_content — Load from string
• export_csv — Export to various formats (csv, tsv, json, excel, parquet, html, markdown)
• get_session_info — Session details
• list_sessions — Active sessions
• close_session — Cleanup

Data manipulation (10)

• filter_rows — Complex filtering
• sort_data — Multi-column sort
• select_columns — Column selection
• rename_columns — Rename columns
• add_column — Add computed columns
• remove_columns — Remove columns
• update_column — Update values
• change_column_type — Type conversion
• fill_missing_values — Handle nulls
• remove_duplicates — Deduplicate

Analysis (7)

• get_statistics — Statistical summary
• get_column_statistics — Column stats
• get_correlation_matrix — Correlations
• group_by_aggregate — Group operations
• get_value_counts — Frequency counts
• detect_outliers — Find outliers (IQR, Z-score)
• profile_data — Data profiling

Validation (3)

• validate_schema — Schema validation
• check_data_quality — Quality metrics + overall score
• find_anomalies — Anomaly detection

Auto-save (4)

• configure_auto_save — Setup auto-save strategy
• disable_auto_save — Turn off auto-save
• get_auto_save_status — Check status
• trigger_manual_save — Force a save now

History (6)

• undo — Step back one operation
• redo — Step forward after undo
• get_history — View operations log
• restore_to_operation — Time travel to a specific operation
• clear_history — Reset history
• export_history — Export operations log

⚙️ Configuration

Environment variables

| Variable | Default | Description | |---|---|---| | CSV_MAX_FILE_SIZE | 1024 (MB) | Maximum file size (megabytes) | | CSV_SESSION_TIMEOUT | 60 (minutes) | Session timeout | | CSV_EDITOR_CSV_HISTORY_DIR | .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
configure_auto_save(
    strategy="backup",
    backup_dir="/backups",
    max_backups=10
)

🛠️ Advanced Installation Options

Alternative Installation Methods

Using pip

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

Using pipx (Global)

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

From PyPI (once v2.0.0 is live)

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

From GitHub

# 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](.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](CONTRIBUTING.md) for guidelines.

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run uv run pytest tests/ and uv run ruff check src/ tests/
5. Submit a pull request

📈 Roadmap

Post-v2.0.0 priorities (see the [2026 relevance audit](specs/2026-04-19-fastmcp3-migration-design.md) 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 load_csv / export_csv / 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](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 →](#-quick-start-2-minutes)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: santoshray02
• Source: santoshray02/csv-editor
• License: MIT
• Homepage: https://santoshray02.github.io/csv-editor/

Install and usage instructions live in the source repository linked above.