MCP ECharts：生成ECharts可视化图表的MCP工具

mcp-echarts 是一个可以让AI大语言模型（LLM）动态生成 Apache ECharts 可视化图表的工具。 它扮演一个模型上下文协议（MCP）服务器的角色，AI助手可以通过调用这个服务，根据用户输入的指令和数据，创建出丰富的图表。 例如，用户可以对AI说“把这份销售数据做成柱状图”，AI就会利用 mcp-echarts 来完成图表的绘制。这个工具的特点是完全在本地运行，不需要依赖任何远程服务，保证了数据的安全性。 同时，它安装简单，并且可以集成 MinIO 对象存储，将生成的图表以链接形式分享，提升了传输和分享的效率。 通过这种方式，mcp-echarts 赋予了AI应用动态数据可视化的能力，使其能更直观地进行数据分析和结果展示。

功能列表

• 全面的ECharts支持：完全支持 Apache ECharts 的所有功能和语法，包括数据、样式、主题等。
• 多种导出格式：支持将生成的图表导出为 png、svg 图片格式，或输出 ECharts 的 option 配置文件。
• 语法校验：内置校验功能，可以帮助AI模型通过多轮对话，最终输出语法正确的图表配置。
• MinIO集成：支持集成 MinIO 对象存储服务。开启后，生成的图表会上传至MinIO并返回一个URL链接，而不是返回Base64数据流，这种方式更适合网络传输和分享。如果未配置MinIO，工具会自动切换回Base64格式输出。
• 轻量化安装：可以通过 npx 命令直接运行，无需复杂的安装过程和外部依赖。
• 本地化运行：图表生成过程完全在本地计算机上完成，不与任何远程服务器通信，确保了数据和隐私的安全性。
• 多种通信协议：支持通过标准输入输出（stdio）、服务器发送事件（sse）和流式传输（streamable）等多种协议与AI应用进行集成。

使用帮助

mcp-echarts 的核心是作为一个后台服务，让AI应用（例如桌面端的Claude、VSCode插件等）可以调用它来生成图表。用户通常不直接操作 mcp-echarts，而是通过配置AI应用来使用它。

1. 快速启动（桌面应用集成）

这是最常见的使用方式，通过AI应用的设置，将 mcp-echarts 指定为一个可用的工具。

配置方法：
在支持MCP协议的AI应用（如Claude桌面版、VSCode等）的配置文件中，添加 mcpServers 部分。

• 在 macOS 系统上：

{
"mcpServers": {
"mcp-echarts": {
"command": "npx",
"args": [ "-y", "mcp-echarts" ]
}
}
}

• 在 Windows 系统上：

{
"mcpServers": {
"mcp-echarts": {
"command": "cmd",
"args": [ "/c", "npx", "-y", "mcp-echarts" ]
}
}
}
```配置完成后，当你在这些应用中向AI发出绘图指令时，AI就会自动调用 `npx -y mcp-echarts` 命令来执行图表生成任务。 `npx -y` 会自动下载并运行最新版本的 mcp-echarts，无需用户手动安装。
### **2. 作为独立服务器运行**
如果你需要将 mcp-echarts 作为一个独立的HTTP服务部署，供其他网络应用（如 glama.ai, smithery.ai 等）调用，可以采用SSE或Streamable模式运行。
**安装**：
首先，需要通过 npm 将其全局安装到你的系统中。
```bash
npm install -g mcp-echarts

启动服务：
根据需要选择一种传输协议来启动服务。

• 以 SSE (Server-Sent Events) 协议运行：

  mcp-echarts -t sse
  

  服务启动后，默认监听在 http://localhost:3033/sse。

• 以 Streamable 协议运行：

  mcp-echarts -t streamable
  

  服务启动后，默认监听在 http://localhost:3033/mcp。

命令行选项：
你可以通过命令行参数自定义服务配置。运行 mcp-echarts -h 查看所有可用选项。

• --transport, -t：指定传输协议，可选值为 stdio (默认)、sse 或 streamable。
• --port, -p：为 sse 或 streamable 协议指定监听端口（默认为 3033）。
• --endpoint, -e：为传输协议指定访问路径（例如，SSE默认为 /sse）。

3. (可选) 配置MinIO对象存储

为了获得更好的性能和分享能力，你可以配置 mcp-echarts 将生成的图表图片上传到MinIO或其他S3兼容的对象存储服务中。

步骤一：启动MinIO服务
首先你需要在本地或服务器上拥有一个正在运行的MinIO服务。以macOS为例，可以使用 brew 快速安装和启动。

# 安装 MinIO
brew install minio/stable/minio
# 启动 MinIO 服务，数据将存储在 ~/minio-data 目录
minio server ~/minio-data --console-address :9001

步骤二：配置环境变量
在 mcp-echarts 项目的根目录下，创建一个 .env 文件。你可以从 .env.example 复制一份来开始。

cp .env.example .env```
然后，编辑 `.env` 文件，填入你的MinIO服务器信息：
```env
MINIO_ENDPOINT=localhost
MINIO_PORT=9000
MINIO_USE_SSL=false
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET_NAME=mcp-echarts

请确保 MINIO_BUCKET_NAME 指定的存储桶（Bucket）已经在MinIO中创建。配置完成后，mcp-echarts 在生成图表后会将其上传并返回一个URL。如果MinIO连接失败，它会自动降级，返回图片的Base64编码。

应用场景

1. AI助手数据可视化
   当用户在与AI助手（如集成在VSCode或Claude中的助手）进行数据分析时，可以直接用自然语言命令AI生成图表。例如，用户可以上传一个CSV文件，然后说：“请根据这个文件的数据，生成一个显示每月销售额的折线图”。AI助手会调用mcp-echarts来完成图表的创建。
2. 自动化报告生成
   在自动生成数据分析报告的系统中，mcp-echarts可以作为一个核心组件。程序在分析完数据后，可以调用mcp-echarts服务，将关键数据和结论转化为图表，并嵌入到最终的报告文档中，使报告内容更具可读性。
3. 在线数据分析平台
   Web应用或在线数据分析平台可以集成mcp-echarts作为后端的图表生成引擎。用户在前端界面上操作数据，平台后端将数据和图表配置发送给mcp-echarts服务，动态生成可视化结果并展示给用户。

QA

1. 什么是 MCP？
   MCP（Model Context Protocol）是一种协议，旨在让大语言模型（LLM）能够与外部工具或服务进行交互。 mcp-echarts 就是一个实现了该协议的服务端工具，它允许AI模型通过调用这个服务来具备生成ECharts图表的能力。
2. mcp-echarts 支持哪些图表类型？
   它理论上支持 Apache ECharts 支持的所有图表类型和功能。因为其核心原理是接收并渲染ECharts的 option 配置，所以只要AI模型能生成正确的配置，mcp-echarts 就能将其渲染出来，包括常见的柱状图、折线图、饼图、散点图以及更复杂的树图、旭日图等。
3. 使用 mcp-echarts 是否需要联网？
   不需要。mcp-echarts 的所有图表生成工作都在本地完成，不依赖任何外部云服务，这保证了数据处理的私密性和安全性。只有在你配置了MinIO对象存储时，它才会连接你指定的MinIO服务器以上传图片。
4. 为什么推荐使用MinIO？
   当AI生成图表后，通常需要将图表（一张图片）返回给前端显示。如果直接返回图片的Base64编码，数据量会很大，传输效率较低。而使用MinIO，可以将图片存入对象存储并返回一个简短的URL，前端加载URL即可，这种方式更高效，也便于分享和管理生成的图表。