✨ 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
• 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.1.0a1"

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.

$ 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.