Overview

This MCP (Model Context Protocol) server provides an easy way to generate interactive Vega-Lite visualizations from data fetched by an LLM or agent. It exposes a small HTTP service that acts as an MCP “renderer” tool: you send a Vega-Lite specification (or a spec plus a data URL/payload) and the server returns an embeddable visualization (HTML fragment or exported image) suitable for insertion into conversational context, notebooks, or dashboards.

The server is useful when you want LLM-driven workflows to produce visual output: the agent fetches data, constructs (or asks the server to construct) a Vega-Lite spec, and then calls the renderer to get a ready-to-display visualization. This separates visualization rendering from the model logic, provides reproducible outputs, and produces interactive charts without requiring the model to host the rendering stack itself.

Features

Render Vega-Lite specs into embeddable HTML fragments (vega-embed) for immediate display
Accept data directly or via a remote data URL (server fetches data)
Optional server-side export to PNG/SVG (configurable; depends on headless Chromium)
Small HTTP API designed to be used as an MCP tool by agents and LLMs
CORS-friendly endpoints for embedding in web UIs
Lightweight configuration (port, export toggles, allowed hosts) via environment variables

Installation / Configuration

Clone the repository and install dependencies. The example below assumes an npm/Node.js implementation; substitute your package manager if needed.

# clone
git clone https://github.com/isaacwasserman/mcp-vegalite-server.git
cd mcp-vegalite-server

# install
npm install

# start (development)
npm run dev

# or production
npm start

Environment variables (example .env):

PORT=8080
ALLOW_ORIGINS=*           # CORS origins, comma-separated
ENABLE_PNG_EXPORT=false   # enable headless browser export to PNG/SVG
MAX_PAYLOAD_SIZE=1mb

If you want server-side PNG/SVG export, install and configure a headless Chromium runtime (Puppeteer). Set ENABLE_PNG_EXPORT=true and ensure the runtime is available to the server process.

Available Tools / Endpoints

The server exposes a small set of HTTP endpoints designed to integrate with MCP-aware agents:

GET /health
- Returns 200 OK if the service is running.
POST /render
- Renders a visualization. Accepts JSON body:
  - spec: object (Vega-Lite spec)
  - data: optional array or object (inline data)
  - data_url: optional string (server will fetch CSV/JSON)
  - output: “html” (default) or “png” | “svg”
- Returns: HTML fragment or binary image depending on output.
POST /tool-meta
- Returns a JSON description of the MCP tool (name, input schema, description) that agents can register.

Example /render request:

curl -X POST http://localhost:8080/render \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
      "mark": "bar",
      "encoding": {
        "x": {"field": "category","type": "nominal"},
        "y": {"field": "value","type": "quantitative"}
      }
    },
    "data": [
      {"category":"A","value":28},
      {"category":"B","value":55},
      {"category":"C","value":43}
    ],
    "output": "html"
  }'

Response: text/html body containing an embeddable div + script that calls vegaEmbed with the provided spec.

MCP Tool Schema Example

If you register the renderer as an MCP tool, provide a schema so agents can call it programmatically. Example tool metadata (JSON):

{
  "name": "vegalite_renderer",
  "description": "Render Vega-Lite specs to embeddable HTML or export images",
  "inputs": {
    "type": "object",
    "properties": {
      "spec": {"type": "object"},
      "data": {"type": ["array","object"]},
      "data_url": {"type": "string"},
      "output": {"type": "string", "enum": ["html","png","svg"]}
    },
    "required": ["spec"]
  }
}

Use Cases

Notebook visualization: Agent fetches a dataset, constructs a Vega-Lite spec, calls the renderer, and inserts the returned HTML fragment into a notebook cell for immediate interactive exploration.
Reporting pipelines: Automated reports generated by an LLM include charts. The report generator posts specs to the renderer and embeds returned PNGs/SVGs into PDFs or HTML reports.
Conversational data exploration: An assistant queries a dataset on behalf of a user, then returns a chart that the user can interact with (hover, zoom) via the embedded Vega runtime.
Validation and preview: During spec generation, an agent can ask the renderer for a quick preview before finalizing a visualization spec.

Examples

Embed returned HTML fragment in a web page:

<!-- server returned this fragment -->
<div id="vis-123"></div>
<script src="https://cdn.jsdelivr.net/npm/vega@5"></script>
<script src="https://cdn.jsdelivr.net/npm/vega-lite@5"></script>
<script src="https://cdn.jsdelivr.net/npm/vega-embed@6"></script>
<script>
  const spec = { /* Vega-Lite spec returned or echoed */ };
  vegaEmbed('#vis-123', spec, {actions: true});
</script>

Request a PNG export (if enabled on server):

curl -X POST http://localhost:8080/render \
  -H "Content-Type: application/json" \
  -d '{"spec": {...}, "data": [...], "output":"png"}' --output chart.png

Vega Lite MCP Server for VegaLite Data Visualizations