# MCP Server Chart  [](https://github.com/antvis/mcp-server-chart/actions/workflows/build.yml) [](https://www.npmjs.com/package/@antv/mcp-server-chart) [](https://smithery.ai/server/@antvis/mcp-server-chart) [](https://www.npmjs.com/package/@antv/mcp-server-chart) [](https://archestra.ai/mcp-catalog/antvis__mcp-server-chart)
A Model Context Protocol server for generating charts using [AntV](https://github.com/antvis/). We can use this MCP server for _chart generation_ and _data analysis_.
โ Server Id 7e8661a3-7e3d-43f8-adef-4be28405a70e
This is a TypeScript-based MCP server that provides chart generation capabilities. It allows you to create various types of charts through MCP tools. You can also use it in [Dify](https://marketplace.dify.ai/plugins/antv/visualization).
## ๐ Table of Contents
- [โจ Features](#-features)
- [๐ค Usage](#-usage)
- [๐ฐ Run with SSE or Streamable transport](#-run-with-sse-or-streamable-transport)
- [๐ฎ CLI Options](#-cli-options)
- [โ๏ธ Environment Variables](#%EF%B8%8F-environment-variables)
- [๐ฆ Sample Data](#-sample-data)
- [VIS_REQUEST_SERVER](#-private-deployment)
- [MAP_REQUEST_SERVER](#-private-deployment)
- [SERVICE_ID](#%EF%B8%8F-generate-records)
- [DISABLED_TOOLS](#%EF%B8%8F-tool-filtering)
- [Built-in Renderer](#built-in-renderer)
- [๐ Private Deployment](#-private-deployment)
- [๐บ๏ธ Generate Records](#%EF%B8%8F-generate-records)
- [๐๏ธ Tool Filtering](#%EF%B8%8F-tool-filtering)
- [๐จ Development](#-development)
- [๐ License](#-license)
## โจ Features
Now 28+ charts supported.
1. `generate_area_chart`: Generate an `area` chart, used to display the trend of data under a continuous independent variable, allowing observation of overall data trends.
1. `generate_bar_chart`: Generate a `bar` chart, used to compare values across different categories, suitable for horizontal comparisons.
1. `generate_boxplot_chart`: Generate a `boxplot`, used to display the distribution of data, including the median, quartiles, and outliers.
1. `generate_choropleth_map`: Generate a `choropleth` map (thematic map), used to visualize statistical data across geographic regions using color shading. Perfect for showing population density, election results, economic indicators, or any metric that varies by region.
1. `generate_color_map`: Generate a `color-map` (color block chart), used to visualize relationships between two categorical dimensions with color-encoded values. Ideal for showing patterns in multi-dimensional categorical data like sales performance, exam scores, or fare matrices.
1. `generate_column_chart`: Generate a `column` chart, used to compare values across different categories, suitable for vertical comparisons.
1. `generate_district_map` - Generate a `district-map`, used to show administrative divisions and data distribution.
1. `generate_donut_chart`: Generate a `donut` chart (doughnut chart), used to display proportional relationships with a hollow center. Features customizable labels, center annotations, and better space utilization than pie charts.
1. `generate_dual_axes_chart`: Generate a `dual-axes` chart, used to display the relationship between two variables with different units or ranges.
1. `generate_fishbone_diagram`: Generate a `fishbone` diagram, also known as an Ishikawa diagram, used to identify and display the root causes of a problem.
1. `generate_flow_diagram`: Generate a `flowchart`, used to display the steps and sequence of a process.
1. `generate_funnel_chart`: Generate a `funnel` chart, used to display data loss at different stages.
1. `generate_histogram_chart`: Generate a `histogram`, used to display the distribution of data by dividing it into intervals and counting the number of data points in each interval.
1. `generate_line_chart`: Generate a `line` chart, used to display the trend of data over time or another continuous variable.
1. `generate_liquid_chart`: Generate a `liquid` chart, used to display the proportion of data, visually representing percentages in the form of water-filled spheres.
1. `generate_mind_map`: Generate a `mind-map`, used to display thought processes and hierarchical information.
1. `generate_network_graph`: Generate a `network` graph, used to display relationships and connections between nodes.
1. `generate_organization_chart`: Generate an `organizational` chart, used to display the structure of an organization and personnel relationships.
1. `generate_path_map` - Generate a `path-map`, used to display route planning results for POIs.
1. `generate_pie_chart`: Generate a `pie` chart, used to display the proportion of data, dividing it into parts represented by sectors showing the percentage of each part.
1. `generate_pin_map` - Generate a `pin-map`, used to show the distribution of POIs.
1. `generate_radar_chart`: Generate a `radar` chart, used to display multi-dimensional data comprehensively, showing multiple dimensions in a radar-like format.
1. `generate_sankey_chart`: Generate a `sankey` chart, used to display data flow and volume, representing the movement of data between different nodes in a Sankey-style format.
1. `generate_scatter_chart`: Generate a `scatter` plot, used to display the relationship between two variables, showing data points as scattered dots on a coordinate system.
1. `generate_treemap_chart`: Generate a `treemap`, used to display hierarchical data, showing data in rectangular forms where the size of rectangles represents the value of the data.
1. `generate_venn_chart`: Generate a `venn` diagram, used to display relationships between sets, including intersections, unions, and differences.
1. `generate_violin_chart`: Generate a `violin` plot, used to display the distribution of data, combining features of boxplots and density plots to provide a more detailed view of the data distribution.
1. `generate_word_cloud_chart`: Generate a `word-cloud`, used to display the frequency of words in textual data, with font sizes indicating the frequency of each word.
> [!NOTE]
> This server renders charts and maps locally. For maps, it uses Leaflet + OSM tiles and Nominatim for geocoding.
## ๐ค Usage
To use with `Desktop APP`, such as Claude, VSCode, [Cline](https://cline.bot/mcp-marketplace), Cherry Studio, Cursor, and so on, add the MCP server config below. On Mac system:
```json
{
"mcpServers": {
"charts-mcp": {
"command": "npx",
"args": [
"-y",
"@antv/mcp-server-chart"
]
}
}
}
```
On Window system:
```json
{
"mcpServers": {
"charts-mcp": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"@antv/mcp-server-chart"
]
}
}
}
```
Also, you can use it on [aliyun](https://bailian.console.aliyun.com/?tab=mcp#/mcp-market/detail/antv-visualization-chart), [modelscope](https://www.modelscope.cn/mcp/servers/@antvis/mcp-server-chart), [glama.ai](https://glama.ai/mcp/servers/@antvis/mcp-server-chart), [smithery.ai](https://smithery.ai/server/@antvis/mcp-server-chart) or others with HTTP, SSE Protocol.
## ๐ฐ Run with SSE or Streamable transport
### Run directly
Install the package globally.
```bash
npm install -g @antv/mcp-server-chart
```
Run the server with your preferred transport option:
```bash
# For SSE transport (default endpoint: /sse)
charts-mcp --transport sse
# For Streamable transport with custom endpoint
charts-mcp --transport streamable
```
Then you can access the server at:
- SSE transport: `http://localhost:1122/sse`
- Streamable transport: `http://localhost:1122/mcp`
### Docker deploy
Enter the docker directory.
```bash
cd docker
```
Deploy using docker-compose.
```bash
docker compose up -d
```
Then you can access the server at:
- SSE transport: `http://localhost:1123/sse`
- Streamable transport: `http://localhost:1122/mcp`
## ๐ฎ CLI Options
You can also use the following CLI options when running the MCP server. Command options by run cli with `-h`.
```plain
MCP Server Chart 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: 1122)
--endpoint, -e Specify the endpoint for the transport:
- For SSE: default is "/sse"
- For streamable: default is "/mcp"
--help, -h Show this help message
```
## โ๏ธ Environment Variables
| Variable | Description | Default | Example |
|----------|:------------|---------|---------|
| `VIS_REQUEST_SERVER` | Chart rendering endpoint | `http://localhost:3210/chart` | `http://localhost:3210/chart` |
| `MAP_REQUEST_SERVER` | Map rendering endpoint | `http://localhost:3210/map` | `http://localhost:3210/map` |
| `SERVICE_ID` | Service identifier for chart generation records | - | `your-service-id-123` |
| `DISABLED_TOOLS` | Comma-separated list of tool names to disable | - | `generate_fishbone_diagram,generate_mind_map` |
| `ENABLED_CHART_TYPES` | Comma-separated list of chart type ids to allow (empty or `*` = all) | `*` (all) | `area,district-map,path-map,pin-map` |
| `RENDER_PORT` | Port for built-in renderer proxy | `3210` | `3210` |
| `RENDER_INTERACTIVE` | When "true", return interactive HTML by default | - | `true` |
| `RENDER_FORMAT` | Force default output format for tools | - | `html` or `png` |
| `UPSTREAM_VIS_REQUEST_SERVER` | Upstream chart renderer (used by built-in proxy) | `https://antv-studio.alipay.com/api/gpt-vis` | `https://your-chart-service/api/gpt-vis` |
| `UPSTREAM_MAP_REQUEST_SERVER` | Upstream map renderer (used by built-in proxy) | - | `https://your-map-renderer/api/gpt-vis` |
## ๐ฆ Sample Data
Sample JSON payloads live under `examples/` and are validated by tests:
- Charts: `examples/charts/*.basic.json` for all chart types (area, bar, boxplot, column, dual-axes, fishbone-diagram, flow-diagram, funnel, histogram, line, liquid, mind-map, network-graph, organization-chart, pie, radar, sankey, scatter, treemap, venn, violin, word-cloud)`
- Maps: `examples/maps/pin-map.basic.json`, `examples/maps/path-map.basic.json`, `examples/maps/district-map.basic.json`
Use them as templates for MCP `callTool` arguments.
## ๐งช Visual Testing
For developers and contributors, we provide a comprehensive visual testing system to validate chart rendering across all three output formats (`html`, `html-url`, `png`).
### Quick Start
```bash
# 1. Start the renderer server
npm run renderer:dev
# 2. In another terminal, generate test renders
npm run render-examples
# 3. Open the interactive gallery
open test-outputs/index.html
```
The gallery provides:
- Side-by-side comparison of all formats
- Interactive viewing of each chart
- PNG thumbnails for quick inspection
- File size information and success rates
For detailed information, see [Visual Testing Guide](docs/VISUAL_TESTING.md).
### Built-in Renderer
This server renders charts and maps locally and serves results via local URLs. To enable it for MCP tools, point envs to the built-in endpoints:
- `VIS_REQUEST_SERVER=http://localhost:3210/chart`
- `MAP_REQUEST_SERVER=http://localhost:3210/map`
Interactive rendering (HTML) is supported by passing `"format": "html"` in the tool arguments:
- Charts example (generate_bar_chart): add `"format": "html"` alongside other fields.
- Maps example (pin/path): include `"format": "html"` inside the `input` payload. For example, pin-map arguments:
- {"title":"Paris Landmarks","data":["Eiffel Tower","Louvre Museum"],"format":"html"}
- District map example (basic): {"title":"รle-de-France Departments","data":{"name":"รle-de-France","dataType":"enum","dataLabel":"Department","subdistricts":[{"name":"Paris","dataValue":"Capital"},{"name":"Seine-et-Marne","dataValue":"Department"}]},"format":"html"}
Notes:
- HTML pages are served from `http://localhost:3210/pages/.html` and are interactive (G2Plot for charts, Leaflet for maps).
- PNG results remain the default when `format` is not provided.
### ๐ Private Deployment
`MCP Server Chart` includes a built-in renderer. You can customize ports and public base if needed.
```json
{
"mcpServers": {
"charts-mcp": {
"command": "npx",
"args": [
"-y",
"@antv/mcp-server-chart"
],
"env": {
"VIS_REQUEST_SERVER": "http://localhost:3210/chart",
"MAP_REQUEST_SERVER": "http://localhost:3210/map"
}
}
}
}
```
The built-in renderer serves local image URLs under `/assets/*`. No external chart service is required. For maps, tiles/geocoding are fetched from public OSM services by default.
- **Method**: `POST`
- **Parameter**: Which will be passed to `GPT-Vis-SSR` for rendering. Such as, `{ "type": "line", "data": [{ "time": "2025-05", "value": 512 }, { "time": "2025-06", "value": 1024 }] }`.
- **Return**: The return object of HTTP service.
- **success**: `boolean` Whether generate chart image successfully.
- **resultObj**: `string` The chart image url.
- **errorMessage**: `string` When `success = false`, return the error message.
> [!TIP]
> If you do not plan to support map generation, disable map tools via `DISABLED_TOOLS`.
### ๐บ๏ธ Generate Records
By default, users are required to save the results themselves, but we also provide a service for viewing the chart generation records, which requires users to generate a service identifier for themselves and configure it.
Use Alipay to scan and open the mini program to generate a personal service identifier (click the "My" menu below, enter the "My Services" page, click the "Generate" button, and click the "Copy" button after success):
Next, you need to add the `SERVICE_ID` environment variable to the MCP server configuration. For example, the configuration for Mac is as follows (for Windows systems, just add the `env` variable):
```json
{
"mcpServers": {
"charts-mcp": {
"command": "npx",
"args": [
"-y",
"@antv/mcp-server-chart"
],
"env": {
"SERVICE_ID": "***********************************"
}
}
}
}
```
After updating the MCP Server configuration, you need to restart your AI client application and check again whether you have started and connected to the MCP Server successfully. Then you can try to generate the map again. After the generation is successful, you can go to the "My Map" page of the mini program to view your map generation records.
### ๐๏ธ Tool Filtering
You can disable specific chart generation tools using the `DISABLED_TOOLS` environment variable. This is useful when certain tools have compatibility issues with your MCP client or when you want to limit the available functionality.
```json
{
"mcpServers": {
"charts-mcp": {
"command": "npx",
"args": [
"-y",
"@antv/mcp-server-chart"
],
"env": {
"DISABLED_TOOLS": "generate_fishbone_diagram,generate_mind_map"
}
}
}
}
```
**Available tool names for filtering** See the [โจ Features](#-features).
## ๐จ Development
Install dependencies:
```bash
npm install
```
Build the server:
```bash
npm run build
```
Start the MCP server:
```bash
npm run start
```
Start the MCP server with SSE transport:
```bash
node build/index.js -t sse
```
Start the MCP server with Streamable transport:
```bash
node build/index.js -t streamable
```
## ๐ License
MIT@[RealTimeX](https://realtimex.ai).