@mseep/csv-editor

v1.0.0

Published

24 days ago

MCP server for comprehensive CSV file operations

0High
0Medium
0Low

skydeckai

mcp mcp-server csv excel data pandas model-context-protocol ai claude llm mseep

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 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,<2 are unaffected and will continue to receive 1.x patches if needed. See CHANGELOG.md for the full list of breaking changes.

🎯 Why CSV Editor?

The Problem

AI assistants struggle with complex data operations - they can read files but lack tools for filtering, transforming, analyzing, and validating CSV data efficiently.

The Solution

CSV Editor bridges this gap by providing AI assistants with 39 specialized tools for CSV operations, turning them into powerful data analysts that can:

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

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

Any MCP-capable client works with stdio transport. See MCP_CONFIG.md for per-client setup.

ChatGPT Connectors require remote Streamable HTTP with OAuth, which is tracked on the 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

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

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/[email protected]

# Or with uv
uv pip install git+https://github.com/santoshray02/[email protected]

🧪 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 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 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 →