ds-mcp-server 0.2.0

An MCP server exposing data science tools (plotting, stats, data exploration) to any LLM client.

ds-mcp-server

ds-mcp-server packages a FastMCP server with data science, plotting, statistics, system, and web tools, plus interactive CLI clients for OpenAI-compatible providers and Anthropic Claude.

Installation

Install from PyPI:

pip install ds-mcp-server

Local development install:

pip install -e .

Optional extras:

pip install -e ".[anthropic]"
pip install -e ".[playwright]"
pip install -e ".[all]"

Quick start

1. Copy .env.example to .env.
2. Fill in your provider settings.
3. Install the package.
4. Start either the MCP server or the interactive client.

OpenAI

export PROVIDER=openai
export API_KEY=sk-...
export MODEL=gpt-4o
ds-mcp-client

Claude / Anthropic

export PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-ant-...
export MODEL=claude-opus-4-5
ds-mcp-client

Gemini (OpenAI-compatible endpoint)

export PROVIDER=gemini
export API_KEY=AIza...
export MODEL=gemini-2.0-flash
ds-mcp-client

Ollama

export PROVIDER=ollama
export API_BASE_URL=http://localhost:11434/v1
export MODEL=llama3
ds-mcp-client

GPUStack / LM Studio / other OpenAI-compatible servers

export PROVIDER=openai-compat
export API_BASE_URL=https://your-endpoint.example/v1
export API_KEY=your-key
export MODEL=your-model
ds-mcp-client

Running the MCP server

ds-mcp-server

To also expose the optional (dangerous) system tools — shell execution, file read/write/patch, background processes, and HTTP requests:

ds-mcp-server --enable-system-tools
# or, equivalently:
DS_MCP_ENABLE_SYSTEM_TOOLS=1 ds-mcp-server

See the Optional system tools section below before enabling.

⚠️ Optional system tools

By default ds-mcp-server only exposes safe read-only data-science tools (plots, statistics, dataset summaries, web fetch/search). A second group of system / coder tools is bundled in the package but is disabled by default because it grants the connected LLM effectively remote-code-execution power.

The gated tools are:

• run_shell_command — runs any shell command with your user's privileges
• read_file, write_file, patch_file, list_directory — arbitrary file I/O
• find_in_files — regex-search anywhere on disk
• run_background_process, stop_background_process, list_background_processes
• http_request — arbitrary outbound HTTP (SSRF risk: can reach localhost, cloud metadata endpoints, internal services, etc.)

Enabling

Only enable inside a sandbox you trust (Docker container, WSL, dedicated VM, or a throwaway user account). The LLM decides when to call these — a single prompt-injection or misinterpretation is enough to trigger destructive actions.

Two equivalent ways to enable:

# Preferred: env var, works with any MCP client (Claude Desktop, LM Studio, …)
export DS_MCP_ENABLE_SYSTEM_TOOLS=1

# Or as a CLI flag when launching the server directly
ds-mcp-server --enable-system-tools

When enabled, the server prints a warning banner to stderr at startup listing every dangerous tool that was registered. When disabled, it prints a one-line hint telling you how to opt in.

Claude Desktop config with system tools enabled

{
  "mcpServers": {
    "ds-mcp-server": {
      "command": "ds-mcp-server",
      "args": ["--enable-system-tools"]
    }
  }
}

🔒 Sandbox for LLM-generated plotting code

Two tools — generate_custom_plotly and generate_custom_static_plot — accept a Python code string produced by the LLM and exec() it in-process to render a plot. Because that code can be influenced by any dataset, webpage, or file the model reads, ds-mcp-server sandboxes it by default.

What the sandbox blocks

• import and from ... import statements (all needed libraries — pd, np, px, go, plt, sns, WordCloud, df — are pre-injected).
• Calls to eval, exec, compile, open, __import__, getattr, setattr, delattr, globals, locals, vars, input, breakpoint.
• Access to any dunder attribute (.__class__, .__subclasses__, etc.) — this closes the common ().__class__.__mro__[-1].__subclasses__() escape.
• Runaway execution — a 60s wall-clock timeout aborts the tool call.

What the sandbox does NOT block (honest limits)

• Filesystem access via pre-imported libraries. pd.read_csv("/etc/passwd") still works because pandas legitimately needs to read files. For strong isolation run the server inside a container, VM, or dedicated user account.
• Native-code CPU/memory exhaustion. Python threads cannot interrupt C extensions, so the timeout is best-effort against numpy/pandas hot loops.

Disabling the sandbox

If you trust the LLM and want unrestricted exec (e.g. for advanced plotting that legitimately needs import), you can opt out:

# Env var (works with any MCP client)
export DS_MCP_ALLOW_UNRESTRICTED_EXEC=1

# Or CLI flag
ds-mcp-server --allow-unrestricted-exec

When disabled, the server prints a warning banner to stderr at startup.

Claude Desktop MCP config

Add the server to your Claude Desktop MCP configuration:

🖥️ Browser chat UI (optional)

Prefer clicking over typing? ds-mcp-server ships with an optional browser-based chat UI that talks to the same MCP server and renders plots inline (interactive Plotly HTML in an iframe, PNG/SVG as images).

Install the extra:

pip install 'ds-mcp-server[web]'

Launch it (with your .env in the current directory or in ~/.env):

ds-mcp-webui                # http://127.0.0.1:8765
ds-mcp-webui --port 9000    # custom port
ds-mcp-webui -p openai -m gpt-4o

Then open the printed URL in your browser. The UI:

• Streams tool calls as they happen (little pill chips per tool).
• Renders generated plots inline — interactive Plotly plots are fully scrollable/zoomable directly in the chat.
• Shows all available MCP tools in a searchable sidebar.
• Works with any provider the CLI client supports (OpenAI, Anthropic, Gemini, Ollama, LM Studio / GPUStack / any OpenAI-compat endpoint).
• Settings panel (⚙ in the sidebar) lets you toggle the dangerous opt-ins — System / coder tools and Unrestricted exec() — with clear warnings. Toggling either one restarts the underlying MCP process so the change takes effect without leaving the browser.

By default it binds to 127.0.0.1 (localhost only). Use --host 0.0.0.0 to expose it on your LAN — but be aware that anyone reaching the port can chat through your API key.

{
  "mcpServers": {
    "ds-mcp-server": {
      "command": "ds-mcp-server",
      "args": []
    }
  }
}

Environment variables

Variable	Required	Description
PROVIDER	No	One of openai, anthropic, gemini, ollama, openai-compat.
API_KEY	Usually	Generic API key used by OpenAI-compatible providers and as a fallback for Anthropic.
ANTHROPIC_API_KEY	Anthropic only	Preferred Anthropic key.
API_BASE_URL	Sometimes	Required for openai-compat; optional override for Ollama, Gemini, or self-hosted endpoints.
MODEL	No	Model override. Defaults are provider-specific.

Available tools

Interactive plots

• plot_interactive_histogram
• plot_interactive_scatterplot
• plot_interactive_boxplot
• plot_interactive_lineplot
• plot_interactive_barchart
• plot_interactive_scatter_matrix
• plot_interactive_correlation_heatmap
• generate_custom_plotly
• get_all_columns_summary
• get_column_summary

Static plots

• plot_static_histogram
• plot_static_scatterplot
• plot_static_boxplot
• plot_static_lineplot
• plot_static_barchart
• plot_static_pairplot
• plot_static_correlation_heatmap
• plot_static_wordcloud
• generate_custom_static_plot

Statistical analysis

• run_correlation
• run_group_comparison
• run_linear_regression
• rank_target_correlations

System tools (opt-in — see Optional system tools)

Only registered when DS_MCP_ENABLE_SYSTEM_TOOLS=1 (or --enable-system-tools).

• run_shell_command
• read_file
• write_file
• patch_file
• list_directory
• find_in_files
• run_background_process
• stop_background_process
• list_background_processes
• http_request

Web tools

• search_web
• fetch_webpage
• screenshot_webpage

Requirements

• Python 3.11+
• mcp
• pandas, numpy
• plotly, matplotlib, seaborn, wordcloud
• pingouin, statsmodels
• beautifulsoup4, ddgs
• openai
• anthropic (optional)
• playwright (optional, for screenshots)