mcp-server-vegalite-viewer

stephaneberle9/mcp-server-vegalite-viewer

3.1

If you are the rightful owner of mcp-server-vegalite-viewer and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Vega-Lite Viewer MCP Server is a tool for creating and displaying interactive data visualizations using Vega-Lite, providing an easy way to generate charts from data and view them in a web browser.

Vega-Lite Viewer MCP Server

A Model Context Protocol (MCP) server that enables creating and displaying interactive data visualizations using the Vega-Lite grammar. This server provides tools to generate charts from data and automatically opens them in a web browser for immediate viewing.

Development

Setup

  • Install Python 3.12 or later

  • Install required development tools:

    # Install build tools and uv package manager
python -m pip install build uv

Run

Inside dev environment

# Create virtual environment
uv venv

# Activate virtual environment
.venv\Scripts\activate  # Windows
source ./.venv/bin/activate  # Linux/macOS

# Install project in editable mode with live code reloading
uv sync

# Run the MCP server (choose one option):

# Option 1: Run as Python module
# (see --help for application CLI options)
mcp-server-vegalite-viewer [application options]
# or
uv run --env-file .env mcp_server_vegalite_viewer [application options]

# Option 2: Run with FastMCP CLI using inferred MCP server instance
# (see fastmcp run --help for FastMCP CLI options)
# Warning: Application CLI options are ignored when using FastMCP CLI
# ----------------------------------------------------------------------
# Note: Apparently, the FastMCP CLI doesn't support Python packages yet.
# Trying to use the command below currently results in this
# 'ERROR Failed to run: attempted relative import with no known parent package'
# ----------------------------------------------------------------------
fastmcp run [FastMCP CLI options] src\mcp_server_vegalite_viewer\mcp_server.py # Windows
fastmcp run [FastMCP CLI options] src/mcp_server_vegalite_viewer/mcp_server.py # Linux/macOS

# Stop the server
# Press Ctrl+C to exit

# Deactivate virtual environment when done
deactivate

Outside dev environment

# Run the MCP server directly from the sources (see --help for CLI options)
uv run --env-file .env --project "/path/to/mcp-server-vegalite-viewer" mcp-server-vegalite-viewer [options]

# Run as editable install to enable live code reloading during development (see --help for CLI options)
uv run --env-file .env --with-editable --project "/path/to/mcp-server-vegalite-viewer" mcp-server-vegalite-viewer [options]

With MCP Inspector

Create an mcp.json file containing:

{
  "mcpServers": {
    "vegalite-viewer": {
      "command": "uv",
      "args": [
        "run",
        "mcp-server-vegalite-viewer",
        "--debug"
      ]
    }
  }
}

From a terminal, start the MCP Inspector:

# Start and open MCP Inspector in your browser
npx -y @modelcontextprotocol/inspector --config mcp.json --server vegalite-viewer

In your browser, connect to your MCP proxy server and use its tools, resources and prompts:

  • Connect to MCP server: Connect or Restart

    :information_source: The local Vega-Lite Viewer MCP server instance is started automatically

  • List tools: Tools > List Tools

  • List resources: Prompts > List Prompts

  • Find MCP proxy server logs under Server Notifications and in %TEMP%\mcp-server-vegalite-viewer.log (Windows) or ${TMPDIR:-/tmp}/mcp-server-vegalite-viewer.log (Linux/macOS)

Check

This project uses pre-commit hooks for running static checks to maintain high code quality standards. These static checks include:

  • Ruff: Python linting and code formatting
  • ty: Modern type checking for Python
  • Prettier: JSON, YAML, and Markdown formatting
  • Codespell: Common spelling error detection
  • pyproject.toml validation: Project configuration validation

Enable automatic execution on git commit

# Activate virtual environment
.venv\Scripts\activate  # Windows
source ./.venv/bin/activate  # Linux/macOS

# Install pre-commit hooks
uv run pre-commit install

Manual execution

# Run all checks on all files
uv run pre-commit run --all-files

# Run individual tools
uv run ruff format          # Code formatting
uv run ruff check --fix     # Linting with auto-fix
uv run ty check             # Type checking

Package

MCP Bundle (formerly Desktop Extension)

To create a MCP Bundle (MCPB) for one-click installation in Claude Desktop:

# Install MCPB CLI globally
npm install -g @anthropic-ai/mcpb

# Activate virtual environment
.venv\Scripts\activate  # Windows
source ./.venv/bin/activate  # Linux/macOS

# Validate MCPB manifest (optional)
mcpb validate manifest.json  # Windows
mcpb validate manifest.json  # Linux/macOS

# Install "fat" package including this MCP server package and all dependencies into `lib` subfolder
uv pip install . --target lib --upgrade

# Create MCP Bundle
mcpb pack . dist\vegalite-viewer.mcpb  # Windows
mcpb pack . dist/vegalite-viewer.mcpb  # Linux/macOS

This will create a dist folder containing a vegalite-viewer.mcpb file that can be easily installed in Claude Desktop as an extension (see here for details).

Python Package Distribution (rarely needed)

For publishing to PyPI or integrating with Python package managers:

# Activate virtual environment
.venv\Scripts\activate  # Windows
source ./.venv/bin/activate  # Linux/macOS

# Install project dependencies
uv sync --no-dev

# Build distribution packages
uv build

This will create a dist folder containing an mcp_server_vegalite-viewer X.X.X.tar.gz and an mcp_server_vegalite-viewer X.X.X-py3-none-any.whl.

Usage

Connect MCP client

Claude Desktop

Option 1: One-click installation using MCP Bundle (recommended)
  1. Create the MCPB bundle (see previous section)
  2. In Claude Desktop, go to Settings... > Extensions
  3. Drag & drop the vegalite-viewer.mcpb file from the dist folder into the Extensions list
  4. Click Install, wait (patiently) until installation is complete, and close the install dialog
  5. Locate the vegalite-viewer in the Extensions list, click Configure and adjust viewer web server port and debug logging to your liking

:no_entry: Apparently, MCP Bundles don't support Python packages yet. While the installation as describe above succeeds, the subsequent start of the Vega-Lite Viewer MCP server fails. Opt for manual installation as a workaround for the time being (see below)

Option 2: Manual configuration using the sources

  • Open Claude Desktop configuration JSON file (accessible from Claude Desktop > Settings... > Developer > Edit config)

  • Add the following entry under mcpServers:

    {
  "mcpServers": {
    "vegalite-viewer": {
      "command": "uv",
      "args": [
        "run",
        "--with-editable",
        "/path/to/mcp-server-vegalite-viewer",
        "mcp-server-vegalite-viewer",
        "--port",
        "8080",
        "--lazy-view"
      ]
    }
  }
}

Example prompts

The following example prompts can be used to test the Vega-Lite Viewer MCP server functionality in Claude Desktop or any other MCP client.

  • Create a simple bar chart for the following JSON dataset and display it in my web browser: [ { "category": "Alpha", "value": 4 }, { "category": "Bravo", "value": 6 }, { "category": "Charlie", "value": 10 }, { "category": "Delta", "value": 3 }, { "category": "Echo", "value": 7 }, { "category": "Foxtrot", "value": 9 } ]