MCP ECharts: MCP tool for generating ECharts visualization charts

mcp-echarts is a tool that allows AI Large Language Models (LLMs) to dynamically generate Apache ECharts visual charts. It acts as a Model Context Protocol (MCP) server that AI assistants can call to create rich charts based on user-input commands and data. For example, the user can say to the AI "make this sales data into a bar chart" and the AI will utilize mcp-echarts to complete the chart. This tool is characterized by running completely locally, without relying on any remote services, ensuring data security. At the same time, it is easy to install and can be integrated with MinIO object storage to share the generated charts in the form of links, which improves the efficiency of transmission and sharing. In this way, mcp-echarts empowers AI applications with the ability to visualize dynamic data, enabling more intuitive data analysis and presentation of results.

Function List

• Full ECharts support: Full support for all features and syntax of Apache ECharts, including data, styles, themes and more.
• Multiple export formats: Supports exporting the generated charts as png,svg image format, or output ECharts' option Configuration file.
• syntax checking: A built-in calibration feature that helps AI models go through multiple rounds of dialog and eventually output syntactically correct chart configurations.
• MinIO integration: Supports integration with MinIO object storage service. When enabled, the generated charts will be uploaded to MinIO and return a URL link instead of a Base64 data stream, which is more suitable for network transmission and sharing. If MinIO is not configured, the tool will automatically switch back to Base64 format output.
• Lightweight installation: This can be done by npx commands run directly without complicated installation processes and external dependencies.
• Localized operation: The chart generation process is done entirely on the local computer and does not communicate with any remote server, ensuring data and privacy security.
• Multiple communication protocols: Supports the use of the standard inputs and outputs via the standard inputs and outputs (stdio), the server sends an event (sse) and streaming (streamable) and many other protocols to integrate with AI applications.

Using Help

At its core, mcp-echarts acts as a background service that AI applications (e.g., Claude on the desktop, VSCode plugins, etc.) can call to generate charts. Users typically do not manipulate mcp-echarts directly, but rather configure AI applications to use it.

1. Quick start (desktop application integration)

This is the most common use, with mcp-echarts specified as an available tool through the AI app's settings.

Configuration method::
In the configuration file for AI applications that support the MCP protocol (e.g., Claude Desktop Edition, VSCode, etc.), add the mcpServers Part.

• On macOS::

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

• On Windows systems::

{
"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

Starting services::
Select a transport protocol to start the service as needed.

• Running on SSE (Server-Sent Events) protocol::

  mcp-echarts -t sse
  

  When the service is started, it defaults to listening on the http://localhost:3033/sseThe

• Runs on Streamable protocol::

  mcp-echarts -t streamable
  

  When the service is started, it defaults to listening on the http://localhost:3033/mcpThe

Command Line Options::
You can customize the service configuration with command line parameters. Run mcp-echarts -h View all available options.

• --transport, -t: Specify the transport protocol, the optional value is stdio (default),sse maybe streamableThe
• --port, -p: for sse maybe streamable The protocol specifies the listening port (the default is 3033).
• --endpoint, -e: Specify the access path for the transport protocol (e.g., SSE defaults to the /sse).

3. (Optional) Configuring MinIO Object Storage

For better performance and sharing capabilities, you can configure mcp-echarts to upload the generated chart images to MinIO or other S3-compatible object storage services.

Step 1: Start the MinIO service
First you need to have a running MinIO service either locally or on a server. In the case of macOS, for example, you can use the brew Quick installation and startup.

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

Step 2: Configure Environment Variables
In the root directory of the mcp-echarts project, create a .env file. You can retrieve the file from the .env.example Make a copy to get started.

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

Please ensure that MINIO_BUCKET_NAME The specified storage bucket (Bucket) has been created in MinIO. Once configured, mcp-echarts uploads the charts after they are generated and returns a URL. if the MinIO connection fails, it automatically downgrades and returns the Base64 encoding of the image.

application scenario

1. AI Assistant Data Visualization
   When users are analyzing data with an AI assistant, such as those integrated into VSCode or Claude, they can command the AI to generate charts directly in natural language. For example, a user can upload a CSV file and say, "Please generate a line chart showing monthly sales based on the data in this file." the AI assistant will call mcp-echarts to complete the chart creation.
2. Automated report generation
   In systems that automatically generate data analysis reports, mcp-echarts can be used as a core component. After analyzing the data, the program can call the mcp-echarts service to transform the key data and conclusions into charts and embed them into the final report document to make the report content more readable.
3. Online data analysis platform
   Web applications or online data analysis platforms can integrate mcp-echarts as the back-end chart generation engine. Users manipulate the data on the front-end interface, and the back-end of the platform sends the data and chart configurations to the mcp-echarts service, which dynamically generates visualization results and displays them to the users.

QA

1. What is MCP?
   MCP (Model Context Protocol) is a protocol designed to enable Large Language Models (LLMs) to interact with external tools or services. mcp-echarts is a server-side tool that implements the protocol, which allows AI models to have the ability to generate ECharts charts by calling this service.
2. What chart types does mcp-echarts support?
   It theoretically supports all chart types and features supported by Apache ECharts. Because its core principle is to receive and render ECharts' option configurations, so as long as the AI model generates the correct configurations, themcp-echarts It will be able to render them, including common bar charts, line charts, pie charts, scatter charts, and more complex tree charts, rising sun charts, and so on.
3. Do I need an internet connection to use mcp-echarts?
   No need.mcp-echarts All chart generation work is done locally without relying on any external cloud services, which guarantees the privacy and security of data processing. It will only connect to the MinIO server you specify to upload images if you have MinIO object storage configured.
4. Why do you recommend MinIO?
   When AI generates a chart, it is usually necessary to return the chart (an image) to the front-end for display. If you directly return the Base64 encoding of the image, the data volume will be very large and the transmission efficiency is low. With MinIO, you can store the image in an object store and return a short URL, and the front-end can just load the URL, which is more efficient and easy to share and manage the generated chart.