CSV Insight & Cleaner MCP 📊🧹

CSV Insight & Cleaner is a minimalistic Model Context Protocol (MCP) server that lets an AI assistant understand, quality-check, and clean CSV datasets — without loading raw file paths or guessing at missing data.

Built with the official Python MCP SDK (FastMCP) and pandas, in a small, readable, single-file codebase.

🌟 Key Highlights

• ⚡ Minimal & Zero-Bloat — one server.py, under 150 lines.
• 🎯 All 3 MCP Primitives: Tools (inspect/summarize/clean/preview/report/export), Resources (live dataset + report snapshots), Prompts (analysis & cleaning workflows).
• 🧠 Facts vs. Explanation split — Python/pandas computes the facts (row counts, duplicates, missing values); the AI client turns those facts into natural language. The server never invents or silently guesses data.
• 🔒 Safe by design — missing values are reported, never auto-filled. Only deterministic, reversible cleanup (duplicates, empty rows, whitespace, column names) is automated.
• 🌐 Deploy-friendly — tools accept raw CSV text content, not local file paths, so the same server works locally and once deployed publicly (e.g. on Glama), where it has no access to your filesystem.

📁 Project Structure

csv-insight-mcp/
├── sample_data/
│   └── messy_sales.csv          # sample dataset for demos
├── src/
│   └── csvinsight/
│       ├── __init__.py          # package exports
│       ├── __main__.py          # `python -m csvinsight` entrypoint
│       └── server.py            # core server (Tools, Resources, Prompts)
├── tests/
│   └── test_server.py           # pytest smoke tests
├── .vscode/
│   └── mcp.json                 # VS Code Copilot Chat MCP config
├── pyproject.toml
└── README.md

📐 Architecture Overview

+-------------------------------------------------------------------------------+
|                                  MCP CLIENT                                   |
|         (VS Code Copilot Chat / Claude Desktop / Cursor IDE / Custom AI)      |
+-------------------------------------------------------------------------------+
                                       ▲
                                       │ JSON-RPC 2.0 (stdio)
                                       ▼
+-------------------------------------------------------------------------------+
|                       CSV INSIGHT & CLEANER MCP SERVER                        |
|                                                                                 |
|   [TOOLS]                     [RESOURCES]                 [PROMPTS]           |
|   • inspect_csv               • csv://current             • analyze_dataset   |
|   • summarize_csv               (dataset snapshot)         • clean_and_report |
|   • preview_csv               • csv://cleaning-report                        |
|   • clean_csv                   (before/after report)                        |
|   • get_cleaning_report                                                       |
|   • export_cleaned_csv                                                        |
+-------------------------------------------------------------------------------+
                                       │
                                       ▼
                            Python / pandas Engine
                         (in-memory dataframe, per session)

🛠️ MCP Primitives Catalog

1. Tools

Tool Name	Parameters	Description
inspect_csv	csv_data: str, filename?: str	Loads raw CSV text and returns rows, columns, dtypes, missing values, duplicates, sample rows.
summarize_csv	none	Returns the same structural facts for the currently loaded dataset.
preview_csv	rows?: int, which?: "original"|"cleaned"	Returns the first N rows of the original or cleaned dataset.
clean_csv	drop_duplicates?, drop_empty_rows?, trim_whitespace?, standardize_columns?: bool	Deterministic cleanup; missing values are reported, never guessed.
get_cleaning_report	none	Returns the before/after report from the last clean_csv call.
export_cleaned_csv	none	Returns the cleaned dataset as raw CSV text, ready to save.

2. Resources

Resource URI	Description
csv://current	Markdown snapshot of the currently loaded dataset (rows, columns, quality).
csv://cleaning-report	Markdown before/after report from the most recent cleaning.

3. Prompts

Prompt Name	Description
analyze_dataset	Workflow: inspect the dataset, explain what it represents, flag quality issues, give recommendations.
clean_and_report	Workflow: clean the dataset, then explain exactly what changed.

🚀 Quickstart

# Clone and enter the project
git clone https://github.com/your-username/csv-insight-mcp.git
cd csv-insight-mcp

# Install in editable mode
pip install -e .

# Run tests
pytest -v

# Run the server directly over stdio
python -m csvinsight

🔌 Client Configuration

VS Code Copilot Chat

Already included at .vscode/mcp.json:

{
  "servers": {
    "csv-insight-cleaner": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "csvinsight"],
      "cwd": "${workspaceFolder}"
    }
  }
}

1. Open Copilot Chat → switch to Agent mode.
2. Click the tools icon → confirm csv-insight-cleaner tools are listed.
3. Try: "Load sample_data/messy_sales.csv and tell me what's wrong with it." (paste the file contents, or ask Copilot to read the file and pass its text into inspect_csv.)

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "csv-insight-cleaner": {
      "command": "python",
      "args": ["-m", "csvinsight"],
      "cwd": "/absolute/path/to/csv-insight-mcp"
    }
  }
}

🎬 Example Demo Flow

"Analyze this CSV." (paste contents of messy_sales.csv)
   → inspect_csv → rows, columns, 1 duplicate row, 1 empty row, 2 missing emails

"What problems does it have?"
   → AI explains the data-quality section in plain language

"Clean the safe issues."
   → clean_csv → duplicates & empty rows removed, columns standardized

"What did you change?"
   → get_cleaning_report → before/after row counts + list of changes

"Give me the cleaned file."
   → export_cleaned_csv → ready-to-save CSV text

☁️ Deployment (Glama)

The server only ever receives CSV text content through its tool parameters — never a local file path — so it is safe to deploy publicly:

1. Push this repository to GitHub.
2. Go to glama.ai/mcp/servers → Add Server.
3. Authenticate with GitHub and submit the repo URL.
4. Glama builds and verifies MCP compliance automatically.

(Smithery is also compatible if preferred — add a smithery.yaml pointing at the same python -m csvinsight entrypoint.)

🧪 Testing

pytest -v

📄 License

MIT License © 2026 CSV Insight & Cleaner Contributors.