Logo

MCP Pandas

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.

Requirements

Python 3.10+
uv (or Docker, for the containerized setup)

Installation

uv venv

uv pip install -e ".[dev]"

Running

The server supports two transports, selected via the MCP_TRANSPORT environment variable (see Configuration).

STDIO

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-pandas

Streamable HTTP

To serve over streamable HTTP instead:

source .venv/bin/activate

MCP_TRANSPORT=http mcp-pandas

The HTTP endpoint is then available at http://0.0.0.0:8080/mcp/.

Docker

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-pandas

Override any setting at runtime with -e, e.g. a different port:

docker run --rm -p 9000:9000 -e MCP_PORT=9000 mcp-pandas

Configuration

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.

Available Tools

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.

Guided Prompts

Prompt	Description
`explore_dataset`	Walks metadata → column analysis → pandas code → visualization.
`visualize_column`	Summarizes a single column and turns its distribution into a chart.

`run_pandas_code` safety

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.

Limits

Maximum input file size: 100 MB.
read_metadata profiles the first 100 rows for speed.
interpret_column_data returns up to 200 distinct values per column.
Supported formats: .csv, .tsv, .txt, .xlsx, .xls.

Project layout

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

Development

Testing

The suite writes fixture files to a temp directory and needs no network:

pytest

License

MIT