mcp-echarts

<img src="https://echarts.apache.org/zh/images/favicon.png" height="24"/> MCP ECharts      

Generate <img src="https://echarts.apache.org/zh/images/favicon.png" height="14"/> Apache ECharts 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 to generate chart, graph, map._

<div align="center"> <img width="648" alt="mcp-echarts" src="https://mdn.alipayobjects.com/huamei_1gdzij/afts/img/A*s3w3SpMMPDQAAAAARzAAAAgAemB7AQ/original" /> </div>

<div align="center"> <img width="648" alt="award" src="https://github.com/user-attachments/assets/962ab78f-387d-412d-81e3-13981328082d" /> </div>

✨ Features

• Fully support all features and syntax of ECharts, include data, style, theme and so on.
• 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.
• MinIO Integration, store charts in MinIO object storage and return URLs instead of Base64 data for better performance and sharing capabilities.
• Lightweight, we can install it easily with zero dependence.
• Extremely secure, fully generated locally, without relying on any remote services.

🤖 Usage

Prerequisites

• Node.js 18 or higher is required.

Desktop Applications (stdio transport)

To use with Desktop APP, such as Claude, VSCode, Cline, Cherry Studio, and so on, add the MCP server config below. On Mac system:

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

On Window system:

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

Also, you can use it on modelscope, glama.ai, smithery.ai or others with HTTP, SSE Protocol.

🚰 Run with SSE or Streamable transport

Install the package globally.

npm install -g mcp-echarts

Run the server with your preferred transport option:

# For SSE transport (default endpoint: /sse)
mcp-echarts -t sse

# For Streamable transport with custom endpoint
mcp-echarts -t streamable

Then you can access the server at:

• SSE transport: http://localhost:3033/sse
• Streamable transport: http://localhost:3033/mcp

🎮 CLI Options

You can also use the following CLI options when running the MCP server. Command options by run cli with -h.

MCP ECharts CLI

Options:
  --transport, -t  Specify the transport protocol: "stdio", "sse", or "streamable" (default: "stdio")
  --port, -p       Specify the port for SSE or streamable transport (default: 3033)
  --endpoint, -e   Specify the endpoint for the transport:
                    - For SSE: default is "/sse"
                    - For streamable: default is "/mcp"
  --help, -h       Show this help message

🗂️ MinIO Configuration (Optional)

For better performance and sharing capabilities, you can configure MinIO object storage to store chart images as URLs instead of Base64 data.

[!NOTE] If MinIO is not configured or unavailable, the system automatically falls back to Base64 data output, ensuring compatibility.

We can Integrate with MinIO object storage providers below.

• MinIO: High-performance, S3-compatible object storage. Use MinIO JavaScript Client for direct integration.
• Amazon S3: Use AWS SDK with compatible API endpoint.
• Alibaba Cloud OSS: Use the Alibaba Cloud SDK for OSS services.
• Google Cloud Storage: Integrate using Google Cloud SDK or compatible API.
• Microsoft Azure Blob Storage: Use Azure SDK for Blob storage access.
• Tencent Cloud COS: Use the Tencent Cloud SDK for COS integration.

Also, we can setup MinIO locally for free.

1. Install and start MinIO locally:

   # Download MinIO (macOS example)
   brew install minio/stable/minio
   
   # Start MinIO server
   minio server ~/minio-data --console-address :9001

1. Configure environment variables:

   # Copy the example environment file
   cp .env.example .env
   
   # Edit .env with your MinIO settings
   MINIO_ENDPOINT=localhost
   MINIO_PORT=9000
   MINIO_USE_SSL=false
   MINIO_ACCESS_KEY=minioadmin
   MINIO_SECRET_KEY=minioadmin
   MINIO_BUCKET_NAME=mcp-echarts

🔨 Development

Install dependencies:

npm install

Build the server:

npm run build

Start the MCP server:

npm run start

🧑🏻‍💻 Contributors

• lyw405: Supports 15+ charting MCP tool. #2
• 2niuhe: Support MCP with SSE and Streaming HTTP. #17
• susuperli: Use MinIO to save the chart image base64 and return the url. #10
• BQXBQX: Use @napi-rs/canvas instead node-canvas. #3
• Meet-student: Add outputType schema for all chart tools. #24
• hustcc: Initial the repo.

📄 License

MIT@hustcc.