echart-mcp-view

Agent-ready ECharts visualization for MCP Apps.

echart-mcp-view is an MCP server that turns structured tool arguments into polished, interactive chart views. It exposes one model-visible opener tool per chart type, serves each chart UI as an independent MCP App HTML resource, and lets the embedded app rebuild ECharts options from validated data without asking the model to hand-write chart configuration.

Highlights

• 16 focused chart apps for tables, Cartesian charts, relationships, hierarchy, flow, KPI, finance, and distribution views.
• MCP Apps first: every opener tool maps to a ui:// HTML resource rendered by a compliant host.
• Structured chart input: callers provide data, encodings, axes, presentation, and interaction controls instead of raw ECharts options.
• Host-aware UI: app chrome follows Host theme, locale, and inline / fullscreen display mode when available.
• Single-file app bundles: every chart surface is built into a self-contained HTML resource under dist/client/.
• Safe customization: advanced.optionPatch accepts controlled style/layout keys while blocking series, datasets, axes, formatter functions, HTML rendering, timelines, and render modes.
• Debuggable by design: optional debug mode reveals input JSON and generated chart options for local inspection.

How It Works

1. The model calls a chart opener tool such as echart_mcp_view_open_line.
2. The tool validates the input and returns structured content plus MCP App metadata.
3. The Host fetches the matching ui://echart-mcp-view/*.html resource and renders it in a sandboxed iframe.
4. The embedded React app receives tool input/result notifications, builds an ECharts option through the app-only helper tool, and renders the chart.

This keeps the model-facing tool surface compact while keeping chart rendering, theme handling, and interactive UI behavior inside the app.

Chart Catalog

Model-visible opener tools:

Chart	Tool	Best for
Table	echart_mcp_view_open_table	Row and column inspection
Line	echart_mcp_view_open_line	Trends, time series, multi-metric comparison
Bar	echart_mcp_view_open_bar	Category comparison, grouped bars, stacked bars
Pie	echart_mcp_view_open_pie	Share-of-total, donut, rose charts
Scatter	echart_mcp_view_open_scatter	Correlation, bubble size, visual maps
Radar	echart_mcp_view_open_radar	Multi-dimensional profile comparison
Heatmap	echart_mcp_view_open_heatmap	Matrix intensity and two-dimensional density
Funnel	echart_mcp_view_open_funnel	Conversion stages and ordered drop-off
Gauge	echart_mcp_view_open_gauge	Single KPI, progress, threshold state
Tree	echart_mcp_view_open_tree	Parent-child hierarchy
Treemap	echart_mcp_view_open_treemap	Hierarchical size comparison
Graph	echart_mcp_view_open_graph	Node-link relationship networks
Sankey	echart_mcp_view_open_sankey	Weighted source-target flows
Candlestick	echart_mcp_view_open_candlestick	OHLC market or range data
Boxplot	echart_mcp_view_open_boxplot	Distribution summaries and outliers
Mixed	echart_mcp_view_open_mixed	Combined bar and line series

App-only helper tools:

Tool	Purpose
echart_mcp_view_app_build_option	Validate chart input and return a table view model or ECharts option for the current app payload
echart_mcp_view_app_examples	Return reusable sample inputs for one chart type or all chart types

Quick Start

Requirements:

• Node.js 20+
• npm

Run the published package over Streamable HTTP:

npx -y echart-mcp-view@latest --http --host 127.0.0.1 --port 3338

Default HTTP endpoints:

http://127.0.0.1:3338/mcp
http://127.0.0.1:3338/healthz

Run over stdio when an MCP host launches this server as a local command:

npx -y echart-mcp-view@latest --stdio

For a source checkout, install and build first:

npm install
npm run build
npm run start

MCP Host Configuration

Recommended stdio configuration with npx:

{
  "mcpServers": {
    "echart-mcp-view": {
      "command": "npx",
      "args": ["-y", "echart-mcp-view@latest", "--stdio"]
    }
  }
}

Pin the version for reproducible host setups:

{
  "mcpServers": {
    "echart-mcp-view": {
      "command": "npx",
      "args": ["-y", "echart-mcp-view@0.1.0", "--stdio"]
    }
  }
}

Source checkout stdio configuration:

{
  "mcpServers": {
    "echart-mcp-view": {
      "command": "node",
      "args": ["/absolute/path/to/echart-mcp-view/dist/index.js", "--stdio"]
    }
  }
}

Streamable HTTP with npx:

npx -y echart-mcp-view@latest --http --host 127.0.0.1 --port 3338

Use the /mcp endpoint in hosts that support Streamable HTTP MCP connections.

NPM Package

The package exposes a single executable:

echart-mcp-view --stdio
echart-mcp-view --http --host 127.0.0.1 --port 3338

Local global install is optional:

npm install -g echart-mcp-view
echart-mcp-view --stdio

Use npx for one-off runs or Host-managed launches:

npx -y echart-mcp-view@latest --stdio
npx -y echart-mcp-view@latest --http --host 127.0.0.1 --port 3338

Runtime Modes

Transports

• --stdio: stdio transport for local MCP host process management.
• --http: Streamable HTTP transport, served at /mcp.
• --host and --port: override HTTP bind host and port.

Environment

ECHART_MCP_VIEW_HTTP_HOST=127.0.0.1
ECHART_MCP_VIEW_HTTP_PORT=3338
ECHART_MCP_VIEW_ALLOWED_ORIGINS=http://localhost:3000
ECHART_MCP_VIEW_ALLOWED_HOSTS=localhost,127.0.0.1
ECHART_MCP_VIEW_HTTP_AUTH_TOKEN=optional-bearer-token
ECHART_MCP_VIEW_DEBUG=0

Remote HTTP mode requires explicit allowed hosts, allowed origins, and an auth token.

Debug Mode

The JSON input and generated-option panel is hidden by default. Enable it when inspecting payloads or chart output:

ECHART_MCP_VIEW_DEBUG=1 node dist/index.js --http --host 127.0.0.1 --port 3338
ECHART_MCP_VIEW_DEBUG=1 node dist/index.js --stdio

For direct local app-page inspection, append ?debug=1 or ?debug=true to the built app URL.

MCP Apps Behavior

• Theme: explicit presentation.theme wins; otherwise the app follows hostContext.theme; without Host context it falls back to prefers-color-scheme.
• Display mode: app capabilities advertise inline and fullscreen; the app requests mode changes through the MCP Apps bridge and trusts the Host result.
• Locale: app chrome uses hostContext.locale when present, then navigator.language, then en-US.
• Host styles: supported Host CSS variables and fonts are applied through the MCP Apps SDK helpers.
• App-only tools: helper tools are marked app-visible so the embedded UI can rebuild options without expanding the model-visible tool set.

Input Contract

Chart opener tools accept chart-specific subsets of the common input model:

Field	Purpose
title	Top-level chart title
subtitle	Top-level chart subtitle
data.source	Tabular rows as object records or a matrix
data.dimensions	Optional ordered field names
data.columns	Table column metadata
data.tree	Hierarchical tree or treemap nodes
data.nodes / data.links	Graph or Sankey relation data
encoding	Mapping from data fields to visual channels
series	Optional per-series overrides
presentation	Theme, palette, labels, legend, stacking, smoothing, orientation
axes	Cartesian or mixed chart axis settings
interaction	Tooltip, legend, zoom, toolbox, visual map
advanced	Renderer and restricted ECharts option patch

Use data.source for tabular charts, data.tree for hierarchy charts, and data.nodes / data.links for graph or Sankey charts. Prefer top-level title and subtitle; presentation fallback titles are accepted by app-side option building.

Line Chart Example

{
  "title": "Revenue by Month",
  "subtitle": "Actuals and profit trend",
  "data": {
    "source": [
      { "month": "Jan", "revenue": 82, "profit": 21 },
      { "month": "Feb", "revenue": 91, "profit": 24 },
      { "month": "Mar", "revenue": 104, "profit": 31 }
    ]
  },
  "encoding": {
    "x": "month",
    "y": ["revenue", "profit"]
  },
  "presentation": {
    "smooth": true,
    "showLegend": true
  },
  "interaction": {
    "tooltip": true,
    "dataZoom": "both"
  }
}

Sankey Example

{
  "title": "Budget Flow",
  "data": {
    "nodes": [
      { "name": "Budget" },
      { "name": "Product" },
      { "name": "Marketing" }
    ],
    "links": [
      { "source": "Budget", "target": "Product", "value": 62 },
      { "source": "Budget", "target": "Marketing", "value": 38 }
    ]
  },
  "interaction": {
    "tooltip": true
  }
}

Architecture

Layer	Files	Responsibility
MCP server	src/mcp/createServer.ts	Register chart opener tools, app-only helpers, and resources
Resource registry	src/mcp/resources/registerResources.ts	Serve ui:// MCP App HTML resources and JSON metadata resources
Chart service	src/services/ChartService.ts	Validate opener payloads and produce structured tool results
Option builder	src/domain/optionBuilder.ts	Convert normalized chart input into table view models or ECharts options
App runtime	src/app/AppRoot.tsx	Connect to the Host, apply theme/locale/display context, render chart UI
App bundles	src/app/pages/*.tsx	One entry point per chart HTML resource
Test harness	tests/mcp-harness/src/run.ts	Exercise stdio and HTTP MCP server behavior

Build output:

Path	Contents
dist/index.js	Compiled MCP server entry
dist/client/mcp-app-*.html	Single-file MCP App HTML resources
dist/**/*.d.ts	Type declarations for compiled modules

Security Notes

• App HTML resources use the MCP Apps resource MIME type and a restrictive empty CSP domain list by default.
• Remote HTTP mode requires host allow-list, origin allow-list, and bearer-token authentication.
• External links are handled by the Host; chart apps do not need broad network access for normal rendering.
• advanced.optionPatch is limited to safe visual/layout keys: aria, backgroundColor, color, dataZoom, grid, legend, textStyle, title, toolbox, tooltip, and visualMap.
• optionPatch rejects nested overrides for generated data structures and executable/rendering fields such as series, dataset, axes, formatter, html, rich, timeline, media, and render mode.

Development

Common scripts:

Script	Description
npm run build	Compile the server and build all app HTML bundles
npm run build:app	Build only the single-file MCP App HTML resources
npm run start	Start HTTP transport from dist/index.js
npm run start:stdio	Start stdio transport from dist/index.js
npm run typecheck	Run TypeScript checks for source and tests
npm test	Run unit tests
npm run test:ui-layout	Build app HTML and verify UI layout snapshots/checks
npm run test:e2e	Run stdio and HTTP MCP harness tests
npm run check	Run typecheck, unit tests, UI layout tests, and MCP harness tests

Verification

Run fast local checks:

npm run typecheck
npm test

Run full verification:

npm run check