Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-pandas Profile the file sales.csv"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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)
Related MCP server: Claude Data Buddy
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-pandasVariable | Default | Description |
|
| Transport to use: |
|
| Host/interface to bind when using HTTP. Use |
|
| Port to listen on when using HTTP. |
|
| Directory where |
Tool | Description |
| Profile a CSV/Excel file: shape, dtypes, null counts, cardinality, sample values, quality warnings and suggested operations (samples the first 100 rows). |
| Full value distribution of one or more columns (scans the whole file). |
| Execute pandas code in a restricted sandbox; optionally preload a file as |
| Render an interactive Chart.js HTML file ( |
Prompt | Description |
| Walks metadata → column analysis → pandas code → visualization. |
| Summarizes a single column and turns its distribution into a chart. |
run_pandas_code safetyThe 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_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.
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.pyThe suite writes fixture files to a temp directory and needs no network:
pytestGenerate an interactive Chart.js HTML file from series data.
Supports bar, line and pie charts. The self-contained HTML is
written to the charts directory (MCP_CHARTS_DIR, default ./charts)
and the tool returns its path. Pie charts use the first series only. Feed
it aggregated data — e.g. the output of a run_pandas_code group-by.
Inputs: data (required), title, chart_type. Returns: object
Return the complete value distribution of one or more columns.
For each requested column, reports dtype, total/null/unique counts and the
value frequencies (sorted most-common first). Unlike read_metadata,
this scans the whole file rather than a sample, so it is ideal for
understanding categorical columns. Frequencies are capped at 200 distinct
values per column.
Inputs: file_path (required), column_names (required), sheet_name. Returns: object
Profile a data file: structure, types, quality warnings and next steps.
Reads only the first rows for efficiency and returns file info, a
per-column profile (dtype, null counts, cardinality, sample values and
numeric min/max/mean), data-quality warnings, and suggested pandas
operations to run next with run_pandas_code. This is the recommended
first call when exploring an unknown dataset.
Inputs: file_path (required). Returns: object
Execute pandas code in a restricted sandbox and return result.
pd (pandas) and np (numpy) are in scope; when file_path is
given, the file is loaded into a DataFrame named df. The code must
assign its output to result. For safety, filesystem/process/interpreter
access (import, open, exec, eval, os/sys/…) is
rejected. DataFrame/Series results are returned as records.
Inputs: code (required), file_path. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 4 tools
Each tool has a distinct purpose: generating charts, profiling metadata, examining column distributions, and executing arbitrary pandas code. There is no overlap or ambiguity.
All tool names use snake_case with a verb_noun pattern, but the verbs vary (generate, read, interpret, run). This is consistent within its own style, though not perfectly uniform.
Four tools is a minimal but focused set for pandas operations. It covers key actions without being overly sparse or excessive for the domain.
Core operations like metadata profiling, column analysis, code execution, and visualization are covered. Minor gaps exist (e.g., no direct data subsetting tool) but arbitrary code fills most needs.
Open, inspect, filter, edit and convert xlsx and csv files from your AI chat. Processing is local.
Open, inspect, filter, edit and convert xlsx and csv files from your AI chat. Processing is local.
Ask questions about a CSV in plain English and get answers, charts and cleaned data back.
AI data analyst: ask about your Excel, CSV, GA4 or database data and get charts and dashboards back