Skip to main content
Glama
ryuk3nd0

echarts-mcp

by ryuk3nd0
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

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. Emits SVG, PNG, and self-contained interactive HTML (PNG needs the optional @napi-rs/canvas dep).

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

  • Multi-format rendering — one call returns any combination of svg (raw vector text, zero native deps), png (base64 image, via optional @napi-rs/canvas), and html (a self-contained interactive page). Deterministic by default (animation: false).

  • Fully stateless — every tool result is self-contained (raw SVG/PNG/HTML + echoed option). No files, no session state, horizontally scalable over HTTP.

  • Optional chart hosting — set MCP_EXPORT_DIR + MCP_EXPORT_BASE_URL and use exportToUrl to persist an artifact and get a public URL for chat platforms.

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

  • Hardened by default — SSRF deny-by-default for remote images, option-depth/complexity bounds, render timeout, constant-time auth, and non-root container. See SECURITY.md.

Related MCP server: ECharts MCP Server

Tools

Tool

Purpose

render_echart

Renders an ECharts option to SVG, PNG, and/or HTML. Returns the artifacts + 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).

formats

("svg" | "png" | "html")[]

["svg"]

Outputs to produce in one call.

width / height

int

800 / 500

Render dimensions in logical pixels (100–4096).

devicePixelRatio

number

2

DPI multiplier for PNG output (1–3).

theme

string | object

"light"

Built-in name or inline theme JSON object.

background

string

"transparent"

e.g. "#ffffff" or "transparent".

animation

boolean

false

Emit animated output when true.

exportToUrl

boolean

false

Persist the artifact and return a public URL (needs hosting config).

The result carries MCP content blocks per requested format — an image block for base64 PNG, a text block for raw SVG and/or HTML — plus structuredContent with formats, width, height, theme, background, version, and (conditionally) svg, pngBytes, html, url, and a warning.

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)

MCP_EXPORT_DIR

export.outputDir

null (disabled)

MCP_EXPORT_BASE_URL

export.baseUrl

null (disabled)

MCP_IMAGE_ALLOW_HOSTS

security.imageAllowHosts

[] (deny all remote images)

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

Enterprise / security suites

pnpm test:security     # adversarial: SSRF guard, bounds, HTML injection, allowlist
pnpm test:stress       # concurrency + pathological-input cliffs
pnpm test:leak         # standalone --expose-gc heap-plateau check
pnpm test:enterprise   # security + stress + leak (release gate)
pnpm audit             # dependency audit (release-time, --audit-level=high)

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

PNG rendering

PNG output uses the optional @napi-rs/canvas dependency (a Rust/Skia binding). It is installed automatically with pnpm install, but if the native binary is unavailable the SVG and HTML paths still work — requesting png without it returns a clear actionable error. Raster rendering is bounded by an 8K-equivalent pixel budget and a maxImageBytes cap (default 8 MiB); oversized images are suppressed with a warning.

Security

The threat model, implemented controls, and accepted residual risks are documented in SECURITY.md. In short: this is a local-first server (stdio), with SSRF denied by default, bounded inputs, and a non-root container. See that file for what is and isn't covered.

Roadmap / deferred

  • Geo/map fetches and custom font registration in the canvas path.

  • Full OAuth 2.1 resource-server auth (optional bearer token today).

  • HTTP-transport hardening (body/concurrency caps) before any hosted deployment.

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.

Available Tools

3 tools
list_chart_typesList chart typesA

Lists common ECharts series types for agent discoverability. Not an allowlist — render_echart accepts any option ECharts v6 supports.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It reveals a key trait: the list is not exhaustive and render_echart accepts any ECharts v6 option, which prevents misuse. It doesn't describe the return format, but for a simple list tool this is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the main purpose, and every clause adds value. The second sentence prevents a common misconception about allowlisting. No redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, no-output-schema tool, the description fully covers what an agent needs to know: what it does, how it relates to render_echart, and its non-exhaustive nature. Nothing is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so the schema is trivially complete. The description doesn't need to add parameter details. Baseline of 4 applies, and the description's mention of ECharts v6 context is a small bonus.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Lists') and resource ('ECharts series types'), clearly stating the tool's purpose. It also distinguishes itself from sibling tools by noting that render_echart accepts any option, clarifying that this list is for discoverability only.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool (for agent discoverability) and explicitly contrasts with render_echart by stating this is not an allowlist. It doesn't mention validate_echart_option or explicitly state when not to use it, but the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

render_echartRender EChartsA

Renders an Apache ECharts visualization server-side (no browser). Returns image (base64 PNG), SVG text, and/or self-contained interactive HTML, selectable via the formats list. PNG requires the optional @napi-rs/canvas dep. For chat-platform targets (Slack/Discord/Telegram), use exportToUrl (needs hosting config).

ParametersJSON Schema
NameRequiredDescriptionDefault
themeNoBuilt-in theme name (e.g. 'light', 'dark') or an inline theme JSON object.light
widthNoRender width in pixels (logical/CSS px).
heightNoRender height in pixels (logical/CSS px).
optionYesStandard Apache ECharts option object (full passthrough to echarts v6).
formatsNoOutput formats to produce in one call: 'svg' (text block with raw SVG), 'png' (image block with base64 PNG; requires optional @napi-rs/canvas), 'html' (text block with a self-contained interactive static HTML page).
animationNoWhether to emit animated output. Disabled by default for deterministic output.
backgroundNoBackground color for the chart (e.g. '#ffffff' or 'transparent').transparent
exportToUrlNoWhen true and chart hosting is configured, also persist the chart and return its public HTTPS URL (for Slack/Discord/Telegram targets).
devicePixelRatioNoDPI multiplier for raster/PNG output.

Output Schema

ParametersJSON Schema
NameRequiredDescription
svgNo
urlNo
htmlNo
themeYesTheme name used ('inline' when a theme object was supplied).
widthYes
heightYes
formatsYes
versionYesPinned echarts runtime version.
warningNo
pngBytesNo
backgroundYes
pngMimeTypeNo

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are absent, so description carries the load. It discloses the server-side behavior, output options, optional dependency for PNG, and the exportToUrl alternative. It doesn't mention failure modes or performance characteristics, but given the context, that's acceptable. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise, informative three sentences. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given complexity (rendering, formats, dependency), description covers key aspects: server-side, output types, dependency requirement, and alternative for chat platforms. Output schema exists, so return values are covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers all 9 parameters with descriptions (100% coverage). The description adds the dependency caveat for PNG and the chat-platform alternative, which are beyond schema. So it adds value above the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool renders Apache ECharts visualizations server-side outputting PNG/SVG/HTML formats. It distinguishes itself from sibling tools like validate_echart_option (validation) and listing chart types by focusing on rendering.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use exportToUrl for chat platforms (Slack/Discord/Telegram) as an alternative, which is a clear usage guideline. It also notes the requirement for hosting configuration, giving strong contextual guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_echart_optionValidate ECharts optionA

Dry-run structural and semantic validation of an ECharts option against echarts@6.1.0 without rendering. Returns errors (would break a render) and warnings (likely mistakes).

ParametersJSON Schema
NameRequiredDescriptionDefault
optionYesThe ECharts option object to validate.

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden of behavioral disclosure. It clearly states it is a dry-run (no rendering) and returns errors and warnings, which are meaningful behavioral traits. It does not detail edge cases or side effects, but the core behavior is transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loaded with the key action ('Dry-run structural and semantic validation') and includes the return value summary. Every word contributes to the user's understanding with no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with no annotations and no output schema, the description effectively covers the tool's purpose, behavioral constraints, and return semantics. It could be more complete by listing example validation rules or the exact return shape, but it is largely sufficient for an AI agent to decide when and how to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already fully describes the only parameter 'option' with a clear description, so baseline is 3. The tool description adds the version context (echarts@6.1.0) and validation scope (structural/semantic) but does not add additional parameter-level meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool performs 'structural and semantic validation of an ECharts option against echarts@6.1.0 without rendering.' It uses a specific verb ('validates') and resource ('ECharts option'), and the 'without rendering' clause distinguishes it from the sibling render_echart tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by noting 'without rendering' and 'dry-run', suggesting it is the safe pre-render check. However, it never explicitly mentions alternative tools or provides when-to-use vs. when-not-to-use guidance relative to siblings render_echart and list_chart_types.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev1.0.0
    • Changedrender_echart25 fields changed
      • changedInput schema / properties / animation / description
        Previous value: -"Whether to emit an animated SVG. Disabled by default for deterministic output."New value: +"Whether to emit animated output. Disabled by default for deterministic output."
      • changedInput schema / properties / devicePixelRatio / description
        Previous value: -"DPI multiplier (raster only)."New value: +"DPI multiplier for raster/PNG output."
      • removedInput schema / properties / devicePixelRatio / exclusiveMinimum
        Removed value: -0
      • addedInput schema / properties / devicePixelRatio / maximum
        Added value: +3
      • addedInput schema / properties / devicePixelRatio / minimum
        Added value: +1
      • addedInput schema / properties / exportToUrl
        Added value: +{
+  "default": false,
+  "description": "When true and chart hosting is configured, also persist the chart and return its public HTTPS URL (for Slack/Discord/Telegram targets).",
+  "type": "boolean"
+}
      • addedInput schema / properties / formats
        Added value: +{
+  "default": [
+    "svg"
+  ],
+  "description": "Output formats to produce in one call: 'svg' (text block with raw SVG), 'png' (image block with base64 PNG; requires optional @napi-rs/canvas), 'html' (text block with a self-contained interactive static HTML page).",
+  "items": {
+    "enum": [
+      "svg",
+      "png",
+      "html"
+    ],
+    "type": "string"
+  },
+  "maxItems": 3,
+  "minItems": 1,
+  "type": "array"
+}
      • changedInput schema / properties / height / description
        Previous value: -"Render height in pixels."New value: +"Render height in pixels (logical/CSS px)."
      • removedInput schema / properties / height / exclusiveMinimum
        Removed value: -0
      • changedInput schema / properties / height / maximum
        Previous value: -9007199254740991New value: +4096
      • addedInput schema / properties / height / minimum
        Added value: +100
      • removedInput schema / properties / renderer
        Removed value: -{
-  "default": "svg",
-  "description": "Output mode: 'svg' (vector, available now) or 'canvas'/'dual' (raster PNG, ships in v1.1).",
-  "enum": [
-    "svg",
-    "canvas",
-    "dual"
-  ],
-  "type": "string"
-}
      • changedInput schema / properties / width / description
        Previous value: -"Render width in pixels."New value: +"Render width in pixels (logical/CSS px)."
      • removedInput schema / properties / width / exclusiveMinimum
        Removed value: -0
      • changedInput schema / properties / width / maximum
        Previous value: -9007199254740991New value: +4096
      • addedInput schema / properties / width / minimum
        Added value: +100
      • addedOutput schema / properties / formats
        Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
      • addedOutput schema / properties / html
        Added value: +{
+  "type": "string"
+}
      • addedOutput schema / properties / pngBytes
        Added value: +{
+  "type": "number"
+}
      • addedOutput schema / properties / pngMimeType
        Added value: +{
+  "type": "string"
+}
      • removedOutput schema / properties / renderer
        Removed value: -{
-  "type": "string"
-}
      • removedOutput schema / properties / svg / description
        Removed value: -"Raw SVG source of the rendered chart."
      • addedOutput schema / properties / url
        Added value: +{
+  "type": "string"
+}
      • addedOutput schema / properties / warning
        Added value: +{
+  "type": "string"
+}
      • changedOutput schema / required
        Previous value: -[
-  "svg",
-  "width",
-  "height",
-  "renderer",
-  "theme",
-  "background",
-  "version"
-]New value: +[
+  "formats",
+  "width",
+  "height",
+  "theme",
+  "background",
+  "version"
+]
  2. 3 tool updatesv0.1.2
    • First observedlist_chart_types
    • First observedrender_echart
    • First observedvalidate_echart_option
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.3/5.0
Disambiguation5/5

render_echart, validate_echart_option, and list_chart_types each address a distinct concern: output generation, option validation, and capability discovery. No two tools overlap in purpose, so agent selection should be straightforward.

Naming Consistency4/5

All tool names use snake_case with a verb-first pattern: render_, validate_, list_. The minor inconsistency is the object noun varying between echart, echart_option, and chart_types, but the overall convention is still predictable.

Tool Count5/5

Three tools cover a narrow, well-defined pipeline: discovering chart types, validating options, and rendering output. This is an appropriate scope with no redundant tools and no obvious missing boilerplate steps.

Completeness4/5

The core workflow is well covered: list_chart_types aids discovery, validate_echart_option prevents render failures, and render_echart produces several output formats. However, render_echart's description references an exportToUrl tool for chat platforms that is not actually part of this server, creating a minor gap for agents aiming at Slack/Discord/Telegram.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • ECharts MCP Server

    w2xi
    A
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol server that generates beautiful chart images from ECharts configurations, supporting various chart types with customizable dimensions.
    19
    7
    MIT

  • ECharts MCP

    apache
    A
    license
    Not graded
    quality
    C
    maintenance
    An MCP (Model Context Protocol) server that enables LLMs to generate ECharts visualizations by accepting chart type, data and parameters and returning cloud image URLs of the generated charts.
    19
    81
    Apache 2.0

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ryuk3nd0/echarts-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server