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).

Related MCP server: ECharts MCP Server

Tools

render_echart inputs

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

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.