holoviz-mcp

✨ HoloViz MCP

A comprehensive Model Context Protocol (MCP) server that provides intelligent access to the HoloViz ecosystem, enabling AI assistants to help you build interactive dashboards and data visualizations with Panel, hvPlot, datashader and your favorite Python libraries.

Please note:

• This MCP server can execute arbitrary Python code when it serves Panel applications (this is configurable, and enabled by default).

✨ What This Provides

Documentation Access: Search through comprehensive HoloViz documentation, including tutorials, reference guides, how-to guides, and API references.

Component Intelligence: Discover and understand 100+ Panel components with detailed parameter information, usage examples, and best practices. Similar features are available for hvPlot.

Extension Support: Automatic detection and information about Panel extensions such as Material UI, Graphic Walker, and other community packages.

Smart Context: Get contextual code assistance that understands your development environment and available packages.

🎯 Why Use This?

• ⚡ Faster Development: No more hunting through docs - get instant, accurate component information.
• 🎨 Better Design: AI suggests appropriate components and layout patterns for your use case.
• 🧠 Smart Context: The assistant understands your environment and available Panel extensions.
• 📖 Always Updated: Documentation stays current with the latest HoloViz ecosystem changes.
• 🔧 Zero Setup: Works immediately with any MCP-compatible AI assistant.

Need more?

Check out the HoloViz MCP Introduction on YouTube.

Other videos: hvPlot tools.

🚀 Quick Start

Requirements

• Python 3.11+ and uv
• VS Code with GitHub Copilot, Claude Desktop, Cursor, or any other MCP-compatible client

Install as a Tool (Recommended)

Due to its size, we strongly recommend installing HoloViz MCP once as a uv tool:

uv tool install git+https://github.com/MarcSkovMadsen/holoviz-mcp[panel-extensions]

This ensures the holoviz-mcp server is installed once, instead of each time it is run as a tool.

Additionally, we highly recommend creating the documentation index (i.e., context) used by holoviz-mcp now, since this process can take up to 10 minutes:

uvx --from holoviz-mcp holoviz-mcp-update # Updates the documentation index used by holoviz-mcp, not the holoviz-mcp Python package.

You may optionally verify you can start the server with the sse transport:

uvx holoviz-mcp

Or, optionally start it with the http transport:

HOLOVIZ_MCP_TRANSPORT=http uvx holoviz-mcp

Use CTRL+C to stop the server when you are finished.

One-Click Install (Also Recommended)

Click the appropriate badge below to install it for usage with a MCP client:

Manual Installation (Alternative to One-Click Install)

{
	"servers": {
		"holoviz": {
			"type": "stdio",
			"command": "uvx",
			"args": [
				"--from",
				"git+https://github.com/MarcSkovMadsen/holoviz-mcp[panel-extensions]",
				"holoviz-mcp"
			]
		}
	},
	"inputs": []
}

{
    "mcpServers": {
        "holoviz": {
            "command": "uvx",
            "args": [
                "--from",
                "git+https://github.com/MarcSkovMadsen/holoviz-mcp[panel-extensions]",
                "holoviz-mcp"
            ]
        }
    }
}

{
    "name": "holoviz",
    "command": "uvx",
    "args": [
        "--from",
        "git+https://github.com/MarcSkovMadsen/holoviz-mcp[panel-extensions]",
        "holoviz-mcp"
    ]
}

{
    "mcpServers": {
        "holoviz": {
            "command": "uvx",
            "args": [
                "--from",
                "git+https://github.com/MarcSkovMadsen/holoviz-mcp[panel-extensions]",
                "holoviz-mcp"
            ]
        }
    }
}

{
    "name": "holoviz",
    "command": "uvx",
    "args": [
        "--from",
        "git+https://github.com/MarcSkovMadsen/holoviz-mcp[panel-extensions]",
        "holoviz-mcp"
    ]
}

That's it! Start asking questions about Panel components, and your AI assistant will have access to comprehensive documentation and component details.

⏱️ First-Time Setup

Installation: The first installation may take 1-2 minutes as dependencies are downloaded and configured.

Documentation Indexing: The first time you search documentation, the system will automatically download and index HoloViz documentation from GitHub. This process takes 5-10 minutes but only happens once. Subsequent searches will be instant.

Progress Monitoring: In VS Code, you can monitor progress in OUTPUT → MCP: holoviz to see indexing status and any potential issues.

💡 What You Can Ask

The AI assistant provides accurate, contextual answers with:

• Detailed component information including all parameters and types
• Usage examples and copy-pasteable code snippets
• Best practices for Panel development
• Extension compatibility information

🛠️ Available Tools

To prevent tools like panel_serve from running arbitrary code, you can disable them by setting one of the following options:

• In your YAML configuration file, set: server.security.allow_code_execution: false
• Or, set the environment variable: HOLOVIZ_MCP_ALLOW_CODE_EXECUTION=false

This will block any features that allow execution of user-provided code.

📦 Installation

For AI Assistant Use

The recommended way is to configure your AI assistant (VS Code + GitHub Copilot) to use the server directly as shown above.

Manual Installation

uv tool install git+https://github.com/MarcSkovMadsen/holoviz-mcp

With Panel Extensions

Install with support for community projects like panel-material-ui, panel-graphic-walker etc.:

uv tool install git+https://github.com/MarcSkovMadsen/holoviz-mcp[panel-extensions]

Running the Server

uvx holoviz-mcp

For HTTP transport:

HOLOVIZ_MCP_TRANSPORT=http uvx holoviz-mcp

⚙️ Configuration Options

uvx holoviz-mcp

HOLOVIZ_MCP_TRANSPORT=http uvx holoviz-mcp

🔄 Updates & Maintenance

Keeping HoloViz MCP up to date ensures you have the latest features, bug fixes, and updated documentation.

Update the Python Package

To update the holoviz-mcp Python package (including code and dependencies):

uv tool update holoviz_mcp[panel-extensions]

Update the Documentation Index

To refresh the searchable documentation index (recommended after package updates, or when new/updated docs are available):

uvx --from holoviz-mcp holoviz-mcp-update

Tips & Tricks

If you are a linux user, then you can make your life easier if you add the below to your .bashrc file

alias holoviz-mcp="uvx holoviz-mcp"
alias holoviz-mcp-update="uv tool update holoviz_mcp[panel-extensions];uvx --from holoviz-mcp holoviz-mcp-update"

After restarting your terminal, you can run:

holoviz-mcp # to start the server
holoviz-mcp-update # to update the python package AND the index

⚙️ User Configuration

HoloViz MCP supports user configuration via a YAML file, allowing you to customize server behavior and documentation sources to fit your workflow.

Custom Configuration File

By default, configuration is loaded from ~/.holoviz-mcp/config.yaml.
To use a different location, set the HOLOVIZ_MCP_USER_DIR environment variable:

export HOLOVIZ_MCP_USER_DIR=/path/to/your/config_dir

Adding Custom Documentation Repositories

You can add documentation from other libraries or your own projects by editing your configuration YAML and adding entries under docs.repositories.

Example: Adding Plotly and Altair Documentation

docs:
  repositories:
    plotly:
      url: "https://github.com/plotly/plotly.py.git"
      base_url: "https://plotly.com/python"
      target_suffix: "plotly"
    altair:
      url: "https://github.com/altair-viz/altair.git"
      base_url: "https://altair-viz.github.io"

After updating your configuration:

1. Update your documentation index:

   holoviz-mcp-update
   

2. Restart the MCP server.

Your custom documentation repositories will now be available for search and reference within HoloViz MCP.

Schema Validation

A schema.json file is provided for configuration validation and editor autocompletion.

For VS Code with vscode-yaml:

Add this at the top of your YAML file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/MarcSkovMadsen/holoviz-mcp/refs/heads/main/src/holoviz_mcp/config/schema.json

This enables real-time validation and autocompletion in VS Code.

🔧 Troubleshooting

Common Issues

Server won't start: Check that Python 3.11+ is installed and verify with pip show holoviz-mcp

VS Code integration not working: Ensure GitHub Copilot Chat extension is installed and restart VS Code after configuration

Missing Panel components: Install relevant Panel extension packages and restart the MCP server

Getting Help

• Issues: Report bugs on GitHub Issues
• Documentation: Check the HoloViz documentation
• Community: Join the HoloViz community on Discord

🛠️ Development

Setup

git clone https://github.com/MarcSkovMadsen/holoviz-mcp
cd holoviz-mcp

Install pixi and run:

pixi run pre-commit-install
pixi run postinstall
pixi run test

Development Server

For remote development with VS Code:

HOLOVIZ_MCP_TRANSPORT=http holoviz-mcp

Add to VS Code workspace .vscode/mcp.json:

{
	"servers": {
		"holoviz": {
			"type": "http",
			"url": "http://127.0.0.1:8000/mcp/",
		}
	},
	"inputs": []
}

Template

This project uses copier-template-panel-extension.

Update to the latest template:

pixi exec --spec copier --spec ruamel.yaml -- copier update --defaults --trust

❤️ Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository and create a new branch
2. Make your changes with tests and documentation
3. Run pixi run test to ensure everything works
4. Submit a pull request

Code Quality

• pre-commit hooks ensure consistent formatting
• pytest for comprehensive testing
• GitHub Actions for CI/CD

Run pixi run pre-commit-install to set up code quality checks.

Roadmap

• Provide Panel and Panel Material UI best practices for both "beginners" and "intermediate" users. Current ones are for "intermediate users".

• Find that "magic" prompt that makes the LLM run a development server with hot reload (panel serve ... --dev) while developing. Would make things more engaging. I've tried a lot.

• Try out Playwright MCP. Its probably worth recommending for taking screenshots and interacting with the app in the browser.

• Provide reference guides for other HoloViz packages starting with hvPlot, param and HoloViews.

• Base index on latest released versions instead of latest code (Head).

• Add dev tools and agents! useful for HoloViz contributors.

• Figure out if there is potential for integrating with or playing together with Lumen AI

• Migrate to HoloViz organisation.