Overview

This MCP (Model Context Protocol) server provides a local toolset for autonomous exploration of CSV datasets. It exposes a set of programmatic tools (file access, Pandas-based analysis, plotting, and a Python executor) that models or agents can call via the MCP protocol to inspect, summarize, and visualize tabular data without manually writing analysis scripts.

The server is intended for developer workflows where a model-driven assistant needs to perform iterative data discovery: generate summary statistics, test hypotheses, create plots, or run small data-cleaning steps. Because the server can execute arbitrary Python code and has filesystem access, run it only in controlled environments and avoid exposing it to untrusted networks or models.

Features

Toolset for CSV data exploration: column summaries, filters, descriptive statistics
Pandas-backed operations and data previews for quick inspection
Plot generation (PNG/SVG) for visual insights
A Python execution tool to run custom analysis snippets on the server
File upload/download endpoints for datasets
MCP-compatible API surface so models or agents can orchestrate multi-step workflows
Simple configuration via environment variables or a config file
Optional Docker image for isolated execution

Installation / Configuration

Prerequisites: Python 3.10+ and pip, or Docker.

Quickstart (local, virtualenv):

# clone the repository
git clone https://github.com/reading-plus-ai/mcp-server-data-exploration.git
cd mcp-server-data-exploration

# create and activate virtual environment
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# install dependencies
pip install -r requirements.txt

Environment configuration (example .env or export):

# Basic configuration
export MCP_HOST=127.0.0.1
export MCP_PORT=3333
export DATA_DIR=./data           # where uploaded CSVs are stored
export LOG_LEVEL=info

Start the server (common patterns — use whichever matches the repo package layout):

# If the project exposes a module entrypoint
python -m mcp_server

# Or, for ASGI servers
uvicorn mcp_server.main:app --host "$MCP_HOST" --port "$MCP_PORT" --reload

Docker (example):

# build
docker build -t mcp-data-explore .

# run (bind local data directory)
docker run -it --rm -p 3333:3333 -v "$(pwd)/data:/app/data" \
  -e MCP_PORT=3333 mcp-data-explore

Security note: this server can execute arbitrary Python and access files in DATA_DIR. Do not run it on production hosts or open it to the public internet.

Available Tools / Resources

Typical tools and endpoints exposed by the server (names may vary slightly depending on configuration):

/status — health and server metadata
/tools — list of MCP-exposed tools and signatures
/upload — POST CSV file for analysis
/files — list and download uploaded datasets
/analyze — high-level operations: head, describe, value_counts, groupby summaries
/plot — request plots (histogram, scatter, boxplot) and receive PNG/SVG
/exec — run arbitrary Python snippets (returns stdout, stderr, and artifacts)

Example tool capabilities:

Tool	Purpose
file_browser	List, preview, and read CSV files
pandas_inspect	Compute describe(), dtype, missing values, unique counts
plotter	Produce visualizations (saved as assets)
python_executor	Execute custom Python (with access to Pandas/DataFrames)

Use Cases

Rapid dataset onboarding: upload a CSV and ask the server (via MCP) for a one-paragraph summary, top 10 rows, and a per-column missing-value report.
- Example flow: POST CSV → /tools/pandas_inspect.describe → /tools/plotter.hist for numeric columns.
Hypothesis testing: iterate with a model that runs correlation checks and suggests possible confounding variables. The model uses the python_executor to compute Pearson/Spearman correlations and request scatter plots for top candidates.
Automated cleaning script generation: ask the server to propose and run a small cleaning pipeline (drop constant columns, impute missing values in numeric columns with median), then preview the cleaned dataset.
Data exploration in notebooks or pipelines: programmatically call the /analyze endpoint to produce summary tables and artifacts that can be embedded into a report or notebook.

Best Practices & Safety

Run locally or behind a firewall. Do not expose the server to untrusted models or users.
Use isolated environments or containers; mount only the directories you intend the server to access.
Limit the Python execution tool if possible (e.g., run in a sandbox, restrict available modules).
Log activity and rotate data directories when working with sensitive datasets.

For the latest details, code, and examples, see the project repository: https://github.com/reading-plus-ai/mcp-server-data-exploration.

MCP Server for Autonomous CSV Data Exploration