✨ dataviz-mcp

DataViz MCP is a local Panel web server and MCP server that executes Python code snippets and renders the resulting visualizations as live, interactive web pages — enabling humans and AI assistants to display and inspect Python outputs in real time.

Features

• Two interfaces — pls serve (standalone browser UI) and pls mcp (MCP server for AI assistants)
• Any visualization library — hvplot · plotly · altair · matplotlib · seaborn · holoviews · bokeh · and more
• Validate before render — show runs syntax, security, package, and extension checks before any rendering happens
• Visual validation — screenshot MCP tool lets the AI inspect the rendered output visually before presenting it
• Adaptive data loading — load_data detects remote, large, multidimensional, and simple tabular data, then selects hvPlot, HoloViews, or Datashader automatically
• Persistent storage — SQLite database with full-text search; every snippet gets its own permanent URL
• Auto-restart — Panel subprocess is health-monitored and automatically restarted on failure
• Works everywhere — local, JupyterHub, GitHub Codespaces; URLs externalized automatically

Installation

Install via uv, pip, or pixi — see the Installation guide for full instructions including how to find your pls path.

uv tool install "dataviz-mcp[pydata]"

Pin your version — this project is in its early stages. Pin to a specific version to avoid unexpected changes: uv tool install "dataviz-mcp[pydata]==0.3.0"

Connect to your AI assistant

Use the absolute path printed by which pls above — not just pls. Full setup instructions for each client: docs → Connect to your MCP client

For the supported desktop and editor clients, let DataViz MCP add just its own configuration entry while preserving any other configured servers:

pls install cursor
# also: vscode, claude-desktop, windsurf, cline, gemini, kiro, copilot

You can tailor the AI guidance without forking the project. Put optional "instructions" and "screenshot" additions in a JSON file, then start the MCP server with pls mcp --prompts rules.json.

Usage

For a safe visual iteration loop, use screenshot(code=...) to review a private draft, use edit(...) for small source changes, then call show(draft_id=...) to publish exactly the reviewed result. Use evaluate(code=...) for text-only Python checks that do not need a rendered visualization.

To load and visualize tabular data automatically, ask the assistant to call load_data(source=...) with a local CSV, JSON, JSONL, NDJSON, or Parquet path, or an HTTP(S) URL. The tool profiles the data and selects hvPlot for simple or remote data, HoloViews for multidimensional data, and Datashader for large data. Set visualize=False when the request is only to inspect or understand the data; the same tool returns schema, quality statistics, a preview, and recommended chart types without creating a visualization or feed entry.

The packaged dataviz-plot-selection skill guides chart choice for trends, comparisons, distributions, relationships, composition, maps, multidimensional exploration, and dashboards. Its guidance is loaded into the MCP server instructions automatically whenever plots are created.

$ pls

 Usage: pls [OPTIONS] COMMAND [ARGS]...

 DataViz MCP - Execute and visualize Python code snippets.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────╮
│ --version  -V        Show version and exit.                                                          │
│ --help               Show this message and exit.                                                     │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────╮
│ serve   Start the DataViz MCP directly.                                                        │
│ mcp     Start as an MCP server for AI assistants.                                                    │
│ status  Check whether the Panel server is running.                                                   │
│ list    List resources (packages, etc.).                                                             │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────╯

You can also use dataviz-mcp but pls is shorter and easier to remember.

Development

See the Contributing guide for the full setup (fork, install, connect to MCP client, run tests).

❤️ Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a new branch: git checkout -b feature/YourFeature.
3. Make your changes and commit them: git commit -m 'Add some feature'.
4. Push to the branch: git push origin feature/YourFeature.
5. Open a pull request.

Please ensure your code passes all tests and linting before submitting.