hsb3/echarts-mcp-server

ECharts MCP Server

Generate interactive charts using Apache ECharts through the Model Context Protocol.

Demo

Try it yourself: npm run demo

Key Features

• 21 Chart Types - Bar, line, pie, scatter, heatmap, network graphs, correlation matrices, and more
• Zero External Dependencies - Pure TypeScript with local JSON generation
• ECharts 6.0 - Latest version with matrix coordinate system support
• Type-Safe - Full TypeScript support with Zod validation
• Multiple Transports - Supports stdio, SSE, and HTTP streaming
• 100% Validated - All chart types tested end-to-end with visual proof

Quick Start

Install dependencies and build:

npm install
npm run build

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "echarts": {
      "command": "node",
      "args": ["/absolute/path/to/echarts-mcp-server/build/index.js"]
    }
  }
}

Restart Claude Desktop to load the server.

Usage Example

Ask Claude to create a chart:

"Create a bar chart showing quarterly sales: Q1: 100, Q2: 150, Q3: 120, Q4: 180"

Claude will use the generate_bar_chart tool and return an ECharts JSON specification. You can then render it using ECharts in your application:

// In your web app
const chartSpec = JSON.parse(response);
echarts.init(document.getElementById('chart')).setOption(chartSpec);

Available Charts (21 Types)

Core (7): bar, column, line, area, pie, scatter, histogram Analytics (7): boxplot, candlestick, heatmap, gauge, radar, parallel, matrix Hierarchical (3): treemap, sunburst, tree Relationships (2): sankey, graph Temporal (1): calendar

All chart types validated with end-to-end tests and visual rendering proof.

Architecture

src/
├── schemas/      - Zod validation schemas for chart inputs
├── generators/   - Chart generation logic (21 types)
└── utils/        - MCP server utilities

Each chart type has:

• Input validation schema (schemas/)
• Generator function returning ECharts JSON (generators/)

Testing

Run comprehensive E2E tests:

npm run test:e2e

Generates 21 PNG files in test/outputs/png/ proving all chart types render correctly.

Requirements

• Node.js 18+
• For Claude Desktop integration: Claude Desktop app

Project Structure

src/
├── schemas/      - Zod validation schemas (21 chart types)
├── generators/   - Chart generation logic (21 modules)
├── utils/        - MCP server utilities
└── services/     - Transport layers (stdio, SSE, HTTP)

test/
├── fixtures/     - Test data for all 21 chart types
├── utils/        - MCP client, renderer, validator
└── integration/  - E2E test suite

assets/
└── demo-charts/  - Visual examples

License

MIT