@realtimex/charts-mcp

MCP Server Chart

A Model Context Protocol server for generating charts using AntV. 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.

📋 Table of Contents

• ✨ Features
• 🤖 Usage
• 🚰 Run with SSE or Streamable transport
• 🎮 CLI Options
• ⚙️ Environment Variables
• 📦 Sample Data
• VIS_REQUEST_SERVER
• MAP_REQUEST_SERVER
• SERVICE_ID
• DISABLED_TOOLS
• Built-in Renderer
• 📠 Private Deployment
• 🗺️ Generate Records
• 🎛️ Tool Filtering
• 🔨 Development
• 📄 License

✨ Features

Now 28+ charts supported.

• 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.
• generate_bar_chart: Generate a bar chart, used to compare values across different categories, suitable for horizontal comparisons.
• generate_boxplot_chart: Generate a boxplot, used to display the distribution of data, including the median, quartiles, and outliers.
• 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.
• 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.
• generate_column_chart: Generate a column chart, used to compare values across different categories, suitable for vertical comparisons.
• generate_district_map - Generate a district-map, used to show administrative divisions and data distribution.
• 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.
• generate_dual_axes_chart: Generate a dual-axes chart, used to display the relationship between two variables with different units or ranges.
• generate_fishbone_diagram: Generate a fishbone diagram, also known as an Ishikawa diagram, used to identify and display the root causes of a problem.
• generate_flow_diagram: Generate a flowchart, used to display the steps and sequence of a process.
• generate_funnel_chart: Generate a funnel chart, used to display data loss at different stages.
• 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.
• generate_line_chart: Generate a line chart, used to display the trend of data over time or another continuous variable.
• generate_liquid_chart: Generate a liquid chart, used to display the proportion of data, visually representing percentages in the form of water-filled spheres.
• generate_mind_map: Generate a mind-map, used to display thought processes and hierarchical information.
• generate_network_graph: Generate a network graph, used to display relationships and connections between nodes.
• generate_organization_chart: Generate an organizational chart, used to display the structure of an organization and personnel relationships.
• generate_path_map - Generate a path-map, used to display route planning results for POIs.
• 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.
• generate_pin_map - Generate a pin-map, used to show the distribution of POIs.
• generate_radar_chart: Generate a radar chart, used to display multi-dimensional data comprehensively, showing multiple dimensions in a radar-like format.
• 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.
• 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.
• 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.
• generate_venn_chart: Generate a venn diagram, used to display relationships between sets, including intersections, unions, and differences.
• 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.
• 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, Cherry Studio, Cursor, and so on, add the MCP server config below. On Mac system:

{
  "mcpServers": {
    "charts-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@antv/mcp-server-chart"
      ]
    }
  }
}

On Window system:

{
  "mcpServers": {
    "charts-mcp": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@antv/mcp-server-chart"
      ]
    }
  }
}

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

🚰 Run with SSE or Streamable transport

Run directly

Install the package globally.

npm install -g @antv/mcp-server-chart

Run the server with your preferred transport option:

# 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.

cd docker

Deploy using docker-compose.

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.

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

# 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.

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/<id>.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.

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

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

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

🔨 Development

Install dependencies:

npm install

Build the server:

npm run build

Start the MCP server:

npm run start

Start the MCP server with SSE transport:

node build/index.js -t sse

Start the MCP server with Streamable transport:

node build/index.js -t streamable

📄 License

MIT@RealTimeX.