MCP Echarts

1# <img src="https://echarts.apache.org/zh/images/favicon.png" height="24"/> MCP ECharts ![](https://badge.mcpx.dev?type=server 'MCP Server')  [![build](https://github.com/hustcc/mcp-echarts/actions/workflows/build.yml/badge.svg)](https://github.com/hustcc/mcp-echarts/actions/workflows/build.yml) [![npm Version](https://img.shields.io/npm/v/mcp-echarts.svg)](https://www.npmjs.com/package/mcp-echarts) [![smithery badge](https://smithery.ai/badge/@hustcc/mcp-echarts)](https://smithery.ai/server/@hustcc/mcp-echarts) [![npm License](https://img.shields.io/npm/l/mcp-echarts.svg)](https://www.npmjs.com/package/mcp-echarts) [![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/hustcc/mcp-echarts)](https://archestra.ai/mcp-catalog/hustcc__mcp-echarts)
2 
3Generate <img src="https://echarts.apache.org/zh/images/favicon.png" height="14"/> [Apache ECharts](https://echarts.apache.org/) with AI MCP dynamically for chart generation and data analysis. _Also you can use <img src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*ZFK8SrovcqgAAAAAAAAAAAAAemJ7AQ/original" height="14"/> [mcp-server-chart](https://github.com/antvis/mcp-server-chart) to generate chart, graph, map._
4 
5<div align="center">
6  <img width="648" alt="mcp-echarts" src="https://mdn.alipayobjects.com/huamei_1gdzij/afts/img/A*s3w3SpMMPDQAAAAARzAAAAgAemB7AQ/original" />
7</div>
8 
9<div align="center">
10  <img width="648" alt="award" src="https://github.com/user-attachments/assets/962ab78f-387d-412d-81e3-13981328082d" />
11</div>
12 
13## ✨ Features
14 
15- Fully support all features and syntax of `ECharts`, include data, style, theme and so on.
16- Support exporting to `png`, `svg`, and `option` formats, with validation for `ECharts` to facilitate the model's multi-round output of correct syntax and graphics.
17- MinIO Integration, store charts in `MinIO` object storage and return URLs instead of Base64 data for better performance and sharing capabilities.
18- Lightweight, we can install it easily with `zero dependence`.
19- Extremely `secure`, fully generated locally, without relying on any remote services.
20 
21 
22## 🤖 Usage
23 
24### Prerequisites
25 
26- Node.js 18 or higher is required.
27 
28### Desktop Applications (stdio transport)
29 
30To use with `Desktop APP`, such as Claude, VSCode, Cline, Cherry Studio, and so on, add the  MCP server config below. On Mac system:
31 
32```json
33{
34  "mcpServers": {
35    "mcp-echarts": {
36      "command": "npx",
37      "args": [
38        "-y",
39        "mcp-echarts"
40      ]
41    }
42  }
43}
44```
45 
46On Window system:
47 
48```json
49{
50  "mcpServers": {
51    "mcp-echarts": {
52      "command": "cmd",
53      "args": [
54        "/c",
55        "npx",
56        "-y",
57        "mcp-echarts"
58      ]
59    }
60  }
61}
62```
63 
64Also, you can use it on [modelscope](https://www.modelscope.cn/mcp/servers/hustcc/MCP-ECharts), [glama.ai](https://glama.ai/mcp/servers/@hustcc/mcp-echarts), [smithery.ai](https://smithery.ai/server/@hustcc/mcp-echarts) or others with HTTP, SSE Protocol.
65 
66 
67## 🚰 Run with SSE or Streamable transport
68 
69Install the package globally.
70 
71```bash
72npm install -g mcp-echarts
73```
74 
75Run the server with your preferred transport option:
76 
77```bash
78# For SSE transport (default endpoint: /sse)
79mcp-echarts -t sse
80 
81# For Streamable transport with custom endpoint
82mcp-echarts -t streamable
83```
84 
85Then you can access the server at:
86- SSE transport: `http://localhost:3033/sse`
87- Streamable transport: `http://localhost:3033/mcp`
88 
89 
90## 🎮 CLI Options
91 
92You can also use the following CLI options when running the MCP server. Command options by run cli with `-h`.
93 
94```plain
95MCP ECharts CLI
96 
97Options:
98  --transport, -t  Specify the transport protocol: "stdio", "sse", or "streamable" (default: "stdio")
99  --port, -p       Specify the port for SSE or streamable transport (default: 3033)
100  --endpoint, -e   Specify the endpoint for the transport:
101                    - For SSE: default is "/sse"
102                    - For streamable: default is "/mcp"
103  --help, -h       Show this help message
104```
105 
106 
107## 🗂️ MinIO Configuration (Optional)
108 
109For better performance and sharing capabilities, you can configure MinIO object storage to store chart images as URLs instead of Base64 data.
110 
111> [!NOTE]
112> If MinIO is not configured or unavailable, the system automatically falls back to `Base64` data output, ensuring compatibility.
113 
114We can Integrate with `MinIO` object storage providers below.
115 
116 - [MinIO](https://min.io/): High-performance, S3-compatible object storage. Use [MinIO JavaScript Client](https://docs.min.io/enterprise/aistor-object-store/developers/sdk/javascript/) for direct integration.
117 - [Amazon S3](https://aws.amazon.com/s3/): Use [AWS SDK](https://aws.amazon.com/sdk-for-javascript/) with compatible API endpoint.
118 - [Alibaba Cloud OSS](https://www.alibabacloud.com/product/object-storage-service): Use the [Alibaba Cloud SDK](https://www.alibabacloud.com/help/en/sdk) for OSS services.
119 - [Google Cloud Storage](https://cloud.google.com/storage): Integrate using [Google Cloud SDK](https://cloud.google.com/sdk) or compatible API.
120 - [Microsoft Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs): Use [Azure SDK](https://azure.microsoft.com/en-us/downloads/) for Blob storage access.
121 - [Tencent Cloud COS](https://intl.cloud.tencent.com/product/cos): Use the [Tencent Cloud SDK](https://intl.cloud.tencent.com/document/product/436/6474) for COS integration.
122 
123Also, we can setup MinIO locally for free.
124 
1251. **Install and start MinIO locally:**
126 
127   ```bash
128   # Download MinIO (macOS example)
129   brew install minio/stable/minio
130   
131   # Start MinIO server
132   minio server ~/minio-data --console-address :9001
133   ```
134 
1353. **Configure environment variables:**
136 
137   ```bash
138   # Copy the example environment file
139   cp .env.example .env
140   
141   # Edit .env with your MinIO settings
142   MINIO_ENDPOINT=localhost
143   MINIO_PORT=9000
144   MINIO_USE_SSL=false
145   MINIO_ACCESS_KEY=minioadmin
146   MINIO_SECRET_KEY=minioadmin
147   MINIO_BUCKET_NAME=mcp-echarts
148   ```
149 
150 
151## 🔨 Development
152 
153Install dependencies:
154 
155```bash
156npm install
157```
158 
159Build the server:
160 
161```bash
162npm run build
163```
164 
165Start the MCP server:
166 
167```bash
168npm run start
169```
170 
171 
172## 🧑🏻‍💻 Contributors
173 
174- [lyw405](https://github.com/lyw405): Supports `15+` charting MCP tool. [#2](https://github.com/hustcc/mcp-echarts/issues/2)
175- [2niuhe](https://github.com/2niuhe): Support MCP with SSE and Streaming HTTP. [#17](https://github.com/hustcc/mcp-echarts/issues/17)
176- [susuperli](https://github.com/susuperli): Use `MinIO` to save the chart image base64 and return the url. [#10](https://github.com/hustcc/mcp-echarts/issues/10)
177- [BQXBQX](https://github.com/BQXBQX): Use `@napi-rs/canvas` instead node-canvas. [#3](https://github.com/hustcc/mcp-echarts/issues/3)
178- [Meet-student](https://github.com/Meet-student): Add `outputType` schema for all chart tools. [#24](https://github.com/hustcc/mcp-echarts/issues/24)
179- [hustcc](https://github.com/hustcc): Initial the repo.
180 
181 
182## 📄 License
183 
184MIT@[hustcc](https://github.com/hustcc).
185