ECharts MCP Server for AI Driven Data Visualization

Overview

The ECharts MCP Server connects natural language AI agents with ECharts to produce dynamic, interactive charts. It implements the Model Context Protocol (MCP) pattern to expose chart-generation and data-inspection capabilities as programmable tools that an LLM or other AI agent can call. This lets developers build applications where users describe a visualization in plain language and receive a ready-to-render ECharts option object in response.

The server is designed for real-time and iterative visualization workflows: it can accept raw data or references to data sources, apply analysis or aggregation steps via model-driven tool calls, and return ECharts configuration JSON that a browser or dashboard can render immediately. That approach reduces boilerplate translation between natural language requests and chart specification, and makes it easier to keep visualizations up-to-date in streaming, monitoring, or exploratory analytics scenarios.

Features

• Exposes MCP-compatible API endpoints so language models can call charting tools programmatically.
• Converts natural-language requests into ECharts option objects (series, axes, tooltips, legends).
• Accepts inline data payloads or links to remote datasets for on-demand aggregation.
• Support for environment-driven configuration (port, model provider keys, CORS).
• Example front-end snippets to render returned ECharts options.
• Logging and basic validation to ensure generated options are safe to render.

Installation / Configuration

Clone the repository and install dependencies (Node.js 16+ recommended):

git clone https://github.com/hustcc/mcp-echarts.git
cd mcp-echarts
npm install

Create a .env file to configure runtime variables. Typical entries:

PORT=3000
MODEL_PROVIDER=openai
OPENAI_API_KEY=sk-xxx
CORS_ALLOWED_ORIGINS=*
LOG_LEVEL=info

Start the server:

# development
npm run dev

# production
npm run build
npm start

By default the server binds to the configured PORT. Model provider keys (OpenAI, Azure, etc.) are read from environment variables; the server delegates model interactions to the configured provider.

Available Tools / Resources

The server exposes a small set of MCP-style resources for LLM tool usage. Endpoints and payload shapes may be customized in configuration; common defaults include:

Typical request/response shapes:

Request (generate):

{
  "prompt": "Show total monthly sales for 2025 with a line and highlight months above target",
  "data": [
    {"month":"2025-01","sales":12000},
    {"month":"2025-02","sales":15000}
  ],
  "options": {"chartTypeHint":"line"}
}

Response (generate):

{
  "echartsOption": {
    "title": {"text":"Monthly Sales 2025"},
    "xAxis": {"type":"category","data":["2025-01","2025-02"]},
    "yAxis": {"type":"value"},
    "series": [{"type":"line","data":[12000,15000],"name":"Sales"}]
  },
  "metadata": {"generatedBy":"mcp-echarts","version":"1.0"}
}

Resources and integrations:

• ECharts documentation: https://echarts.apache.org
• Model Context Protocol (MCP) – use server-side docs in the repo for exact spec and customization.

Use Cases

1. Natural-Language Business Analytics

   • A BI web app lets non-technical users ask “Compare last quarter revenue by product category” and receives a multi-series bar chart option to render immediately with ECharts.

2. Real-time Monitoring Dashboards

   • Streaming metrics are pushed into the server; an agent automatically selects chart types, aggregates by minute, and returns ECharts options for dashboards that update without manual chart configuration.

3. Assisted Data Exploration

   • Data scientists can query datasets in plain English (“Show outliers in response times”) and get an ECharts scatter plot with highlighted points and suggested drill-down filters. The MCP server can include an inspect call to summarize columns before charting.

4. Automated Reporting Pipelines

   • Scheduled jobs send summarized metrics and a templated prompt to the MCP server, which returns a set of chart options embedded into a report builder (PDF/HTML generation pipeline).

Quick Front-end Rendering Example

Minimal HTML/JS to render the returned option (assuming echarts is available on the page):

<div id="chart" style="width:600px;height:400px"></div>
<script src="https://cdn.jsdelivr.net/npm/echarts/dist/echarts.min.js"></script>
<script>
  fetch('/mcp/generate', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
      prompt: 'Show monthly users',
      data: [{month:'Jan',value:100},{month:'Feb',value:150}]
    })
  }).then(r => r.json()).then(res => {
    const chart = echarts.init(document.getElementById('chart'));
    chart.setOption(res.echartsOption);
  });
</script>

Tips and Next Steps

• Validate returned options before rendering if you accept untrusted input.
• Tune model prompts and tool definitions to control chart grammar (preferred series types, color palettes).
• Use the inspect endpoint to pre-process or sanitize tabular inputs for better chart suggestions.
• Check the repository’s examples folder for additional integration patterns and sample prompts.

For exact API details and extension points, see the repository README and the configuration files included in the project.