echarts-mcp

A modern, open-source Apache ECharts MCP server. It exposes type-safe tools that let AI agents and chat UIs render rich, deterministic charts server-side — no browser, no native canvas dependency.

Built against the Model Context Protocol v2 SDK (@modelcontextprotocol/server@2) and Apache ECharts 6.1.0 (pinned), supporting both stdio and Streamable HTTP transports.

Highlights

• SVG-first rendering — echarts.init(null, theme, { renderer: "svg", ssr: true }) + renderToSVGString() produces clean, scalable vector output with zero native dependencies and no DOM. Deterministic by default (animation: false).
• Fully stateless — every tool result is self-contained (raw SVG + echoed option). No files, no session state, horizontally scalable over HTTP.
• Type-safe tool surface — JSON Schema derived from Zod v4 (Standard Schema), so agents get precise, machine-readable input/output contracts.
• Passthrough fidelity — render_echart accepts any ECharts v6 option; it does not restrict chart types (see list_chart_types for discoverability only).

Tools

Tool	Purpose
render_echart	Renders an ECharts option to SVG. Returns the raw SVG + echoed option.
validate_echart_option	Dry-run structural + semantic validation (pinned to echarts@6.1.0) without rendering.
list_chart_types	Lists common series types for agent discoverability (not an allowlist).

render_echart inputs

Param	Type	Default	Notes
option	object	required	Full ECharts v6 option (passthrough).
renderer	"svg" | "canvas" | "dual"	"svg"	canvas/raster ships in v1.1.
width / height	int	800 / 500	Render dimensions in pixels.
devicePixelRatio	number	2	Raster only (deferred).
theme	string | object	"light"	Built-in name or inline theme JSON object.
background	string	"transparent"	e.g. "#ffffff" or "transparent".
animation	boolean	false	Emit an animated SVG when true.

The result carries an MCP text content block (the raw SVG) plus structuredContent with svg, width, height, renderer, theme, background, and version.

Quick start

Requires Node.js 20+ (developed on Node 24) and pnpm.

pnpm install
pnpm build          # compiles src/ -> dist/
pnpm dev            # run via tsx (stdio)
pnpm start          # run the compiled dist (stdio)

Run the server over stdio (the default) from an MCP client by pointing it at dist/index.js.

Install from npm

npm install -g @ryuk3nd0/echarts-mcp
# then use it from any MCP client:
echarts-mcp
# or ad-hoc without a global install:
npx -y @ryuk3nd0/echarts-mcp

Streamable HTTP

MCP_TRANSPORT=streamable-http MCP_HTTP_PORT=3030 node dist/index.js

The MCP endpoint is then available at http://localhost:3030/mcp.

Configuration

Configuration is resolved in this precedence order (highest first):

1. Environment variables
2. A JSON config file (MCP_CONFIG path, or ./config.json when present)
3. Built-in defaults

Env var	Config key	Default
MCP_TRANSPORT	transport	stdio
MCP_HTTP_HOST	http.host	0.0.0.0
MCP_HTTP_PORT	http.port	3030
MCP_HTTP_PATH	http.path	/mcp
MCP_API_TOKEN	http.authToken	null (disabled)

See config.example.json for the full shape.

Authentication (Streamable HTTP only)

By default the HTTP endpoint is open (intended for trusted localhost). To protect it, set MCP_API_TOKEN (or http.authToken in config.json). Clients must then send Authorization: Bearer <token>; requests without a matching token receive 401.

Development

pnpm typecheck     # tsc --noEmit
pnpm lint          # eslint
pnpm test          # vitest run
pnpm format        # prettier

Docker

docker build -t echarts-mcp .
# stdio
docker run -i --rm echarts-mcp
# streamable HTTP
docker run -p 3030:3030 -e MCP_TRANSPORT=streamable-http echarts-mcp

Roadmap / deferred

• Canvas/PNG raster engine (v1.1): requires a DOM shim + @napi-rs/canvas + echarts.setPlatformAPI({ createCanvas, loadImage, measureText }) + font registration.
• Full OAuth 2.1 resource-server auth (optional bearer token today).

License

Apache-2.0. See LICENSE.

Integrations

Ready-to-paste client config snippets live in integrations/:

• integrations/claude-desktop.json — Claude Desktop stdio entry.
• integrations/mcp.json — generic stdio entry (Claude Code, Cursor, and others).
• integrations/streamable-http.json — remote Streamable HTTP endpoint for gateways and hosted LLM tool integrations.

A machine-readable SKILL.md at the repo root describes the server for Agent Skills systems. The same guidance is exposed to MCP clients via the server's instructions field.