Vizro MCP Server: Validated, Maintainable Dashboards & Charts

Overview

The Vizro MCP (Model Context Protocol) Server provides a lightweight, local service for producing validated, maintainable dashboards and charts from structured data and natural-language prompts. It implements an MCP-style interface that standardizes how models (LLMs) and tools exchange context, templates, and structured outputs so teams can generate visualizations that are repeatable and verifiable.

This server is useful when you want to (1) let analysts or apps describe visualizations in plain language, (2) convert those requests into a concrete chart specification (for Vega-Lite, Chart.js, etc.), and (3) validate and version the result so dashboards remain accurate and auditable. The MCP server bundles template libraries, validators, and render helpers so you can integrate chart generation into pipelines, UIs, or CI workflows without ad-hoc code every time.

Features

• Template-driven chart generation: reusable visualization templates parametrized by data and intent.
• Schema validation: validate chart specs (JSON Schema, Vega-Lite schema) before rendering or deployment.
• Tool interfaces for LLMs: expose visualization-building tools that can be called by model agents (MCP-conformant).
• Render previews: local rendering or export to PNG/SVG for review.
• CLI and server modes: run locally for development or as a service in production.
• Extensible template and validator directories for team customization.
• Audit-friendly outputs: versioned specs, validation reports, and provenance metadata.

Installation / Configuration

Prerequisites: Node 18+ and npm or Docker.

Clone and run locally (npm):

git clone https://github.com/mckinsey/vizro.git
cd vizro/vizro-mcp
npm install
# Start in development mode
npm run dev
# Or build & run
npm run build
npm start

Run with Docker:

# build
docker build -t vizro-mcp .
# run
docker run -p 8080:8080 \
  -e PORT=8080 \
  -e OPENAI_API_KEY=your_key_here \
  -e TEMPLATES_DIR=/data/templates \
  -v $(pwd)/templates:/data/templates \
  vizro-mcp

Environment variables

• PORT: HTTP port (default: 8080)
• OPENAI_API_KEY: optional, for LLM-backed flows
• TEMPLATES_DIR: local path to visualization templates
• VALIDATORS_DIR: local path to custom validation rules

Configuration file (optional config.json):

{
  "port": 8080,
  "templatesDir": "./templates",
  "validatorsDir": "./validators",
  "renderers": ["vega-lite", "chartjs"]
}

API Endpoints (quick reference)

Example: Generate a chart (curl)

curl -X POST http://localhost:8080/mcp/generate \
  -H "Content-Type: application/json" \
  -d '{
    "template": "timeseries-trend",
    "params": {
      "title": "Monthly Revenue",
      "xField": "month",
      "yField": "revenue",
      "dataUrl": "https://example.com/data/revenue.csv"
    },
    "context": {
      "user": "[email protected]",
      "project": "Q2-analysis"
    }
  }'

Sample response (abbreviated):

{
  "spec": { /* Vega-Lite spec JSON */ },
  "validation": { "ok": true, "errors": [] },
  "metadata": { "template": "timeseries-trend", "version": "1.0.0" }
}

Available Tools / Resources

• Template library: collection of parameterized templates (Vega-Lite/JSON) for common charts — timeseries, bar, stacked, scatter, KPI cards.
• Validators: JSON Schema validators and custom rule sets (e.g., checks for axes labels, aggregations, color contrast).
• Rendering backends: Vega/Vega-Lite server-side renderer (exports PNG/SVG) and browser preview integration.
• CLI: commands to list templates, validate specs, and render previews locally.
• Integration helpers: small client libraries and examples for Node and Python to call the MCP server from apps or bots.

Repository link and examples:

• GitHub: https://github.com/mckinsey/vizro/tree/main/vizro-mcp

Use Cases

1. Analyst: Natural-language to chart via notebook

   • Analyst types: “Show monthly revenue trend for 2025 with a 3-month moving average.”
   • Notebook calls /mcp/generate with the timeseries template and data URL; server returns a validated Vega-Lite spec and a quick PNG preview that the analyst can inspect and embed.

2. BI Pipeline: CI validation of dashboards

   • A CI job ensures every dashboard spec in the repo passes schema and business-rule validation before merging. Use /mcp/validate as part of CI to prevent broken visualizations reaching production.

3. Model-Aided Visualization (LLM agent)

   • An LLM agent constructs a visualization by calling MCP tools exposed by the server (list templates, generate spec, validate, render). The MCP server acts as a reliable tool endpoint, returning structured outputs the agent can reason about.

4. Embedded preview in apps

   • A data app posts user-selected parameters to the MCP server to derive a spec and preview image. The app stores the validated spec alongside data version metadata, enabling reproducible dashboards.

Getting Started Tips

• Start by browsing the templates directory and reusing existing templates before authoring new ones.
• Add custom validation rules for domain-specific constraints (e.g., currency formatting).
• Use the render endpoint to automate screenshot generation for documentation or reports.
• Version templates and validators in your repository to keep chart behavior stable across releases.

For implementation details, examples, and the full codebase, see the project on GitHub: https://github.com/mckinsey/vizro/tree/main/vizro-mcp.