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.

Related MCP server: mcp-plots

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:

App-only helper tools:

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.1", "--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:

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

Build output:

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:

Verification

Run fast local checks:

npm run typecheck
npm test

Run full verification:

npm run check