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

Available Tools

Guided Prompts

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