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", "[email protected]", "--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.

Radar charts accept both wide rows (encoding.name plus metric fields in encoding.y) and long rows (encoding.category for indicators, with either value columns in encoding.y or grouped encoding.series plus encoding.value).

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