A modern Model Context Protocol server for pandas-based data analysis. Point it at a CSV/Excel file and it profiles the data, explains individual columns, runs sandboxed pandas code, and renders interactive charts.
Exposes 4 tools and 2 guided prompts. Functionality inspired by
marlonluo2018/pandas-mcp-server.
- Python 3.10+
- uv (or Docker, for the containerized setup)
uv venv
uv pip install -e ".[dev]"The server supports two transports, selected via the MCP_TRANSPORT environment variable (see Configuration).
The server speaks MCP over stdio by default (the transport used by most MCP clients such as Claude Desktop and Claude Code):
source .venv/bin/activate
mcp-pandasTo serve over streamable HTTP instead:
source .venv/bin/activate
MCP_TRANSPORT=http mcp-pandasThe HTTP endpoint is then available at http://0.0.0.0:8080/mcp/.
Build the image and run it in HTTP mode (the image defaults to HTTP on port 8080):
docker build -t mcp-pandas .
docker run --rm -p 8080:8080 mcp-pandasOverride any setting at runtime with -e, e.g. a different port:
docker run --rm -p 9000:9000 -e MCP_PORT=9000 mcp-pandas| Variable | Default | Description |
|---|---|---|
MCP_TRANSPORT |
stdio |
Transport to use: stdio or http (streamable HTTP). |
MCP_HOST |
0.0.0.0 |
Host/interface to bind when using HTTP. Use 0.0.0.0 to expose it. |
MCP_PORT |
8080 |
Port to listen on when using HTTP. |
MCP_CHARTS_DIR |
charts |
Directory where generate_chartjs writes HTML files. |
| Tool | Description |
|---|---|
read_metadata |
Profile a CSV/Excel file: shape, dtypes, null counts, cardinality, sample values, quality warnings and suggested operations (samples the first 100 rows). |
interpret_column_data |
Full value distribution of one or more columns (scans the whole file). |
run_pandas_code |
Execute pandas code in a restricted sandbox; optionally preload a file as df. |
generate_chartjs |
Render an interactive Chart.js HTML file (bar, line, pie) from series data. |
| Prompt | Description |
|---|---|
explore_dataset |
Walks metadata → column analysis → pandas code → visualization. |
visualize_column |
Summarizes a single column and turns its distribution into a chart. |
The executed code runs with a replaced __builtins__ and a pattern filter. It
must assign its output to a variable named result, and constructs that escape
the sandbox are rejected: import, open, exec, eval, and references to
os/sys/subprocess/shutil/socket/dunder attributes. pd (pandas) and
np (numpy) are available; pass file_path to preload the data as df.
- Maximum input file size: 100 MB.
read_metadataprofiles the first 100 rows for speed.interpret_column_datareturns up to 200 distinct values per column.- Supported formats:
.csv,.tsv,.txt,.xlsx,.xls.
src/mcp_pandas/
├── server.py # FastMCP instance, registration, transport entry point
├── loader.py # shared file loading, validation, memory optimization
├── utils.py # code-safety and column validation helpers
├── charting.py # Chart.js HTML generation
├── prompts.py # guided prompts
└── tools/ # one module per tool, each exposing register(mcp)
├── metadata.py
├── columns.py
├── execution.py
└── charts.py
The suite writes fixture files to a temp directory and needs no network:
pytest