# ai-mcp-chart-vis

> **开箱即用的 MCP 图表服务，支持 26+ 种图表类型。**
> 自动启动私有渲染服务，无需手动操作任何进程。

兼容 **Cursor**、**Claude Desktop**、**VS Code + Cline** 等任意支持 MCP 的 AI 客户端。

---

## 快速安装

### Cursor

打开 **Cursor Settings → MCP**，添加以下配置：

```json
{
  "ai-mcp-chart-vis": {
    "command": "npx",
    "args": ["-y", "github:yanbober/ai-mcp-chart-vis"]
  }
}
```

### Claude Desktop

编辑配置文件：
- Windows：`%APPDATA%\Claude\claude_desktop_config.json`
- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ai-mcp-chart-vis": {
      "command": "npx",
      "args": ["-y", "github:yanbober/ai-mcp-chart-vis"]
    }
  }
}
```

### VS Code + Cline

在 VS Code 设置（`Ctrl+,`）中搜索 `cline.mcp`，编辑 `settings.json`：

```json
{
  "cline.mcp.mcpServers": {
    "ai-mcp-chart-vis": {
      "command": "npx",
      "args": ["-y", "github:yanbober/ai-mcp-chart-vis"]
    }
  }
}
```

配置完成即可使用，**无需 clone 代码、无需 npm install、无需配置环境变量。**

---

## 图片存储位置

每次 AI 生成图表时，PNG 文件会保存在本地。

**默认路径：**

| 系统 | 路径 |
|---|---|
| Windows | `C:\Users\你的用户名\.ai-mcp-chart-vis\output\` |
| macOS / Linux | `~/.ai-mcp-chart-vis/output/` |

> 图片文件名格式：`chart-<时间戳>.png`，例如 `chart-1772787477665.png`

---

## 环境变量配置

所有配置均通过 MCP 配置中的 `"env"` 字段设置，无需创建任何配置文件。

| 变量 | 说明 | 默认值 |
|---|---|---|
| `VIS_PORT` | 渲染服务端口 | `8888` |
| `VIS_OUTPUT_DIR` | 图片保存目录 | `~/.ai-mcp-chart-vis/output` |
| `VIS_CLEANUP` | 会话结束后自动删除本次图片 | `false` |
| `VIS_REQUEST_SERVER` | 渲染 API 完整地址（一般无需设置） | 由 `VIS_PORT` 自动推导 |

### 示例：自定义所有配置项

```json
{
  "ai-mcp-chart-vis": {
    "command": "npx",
    "args": ["-y", "github:yanbober/ai-mcp-chart-vis"],
    "env": {
      "VIS_PORT":       "8889",
      "VIS_OUTPUT_DIR": "D:/我的图表",
      "VIS_CLEANUP":    "true"
    }
  }
}
```

---

## 端口冲突处理

渲染服务默认占用端口 **8888**。

**端口被占用时**，通过 `VIS_PORT` 换用其他端口：

```json
{
  "ai-mcp-chart-vis": {
    "command": "npx",
    "args": ["-y", "github:yanbober/ai-mcp-chart-vis"],
    "env": { "VIS_PORT": "8889" }
  }
}
```

**同时打开多个 Cursor 窗口？** 无冲突——第二个窗口检测到端口已有服务运行，直接复用，不会重复启动。

---

## 工作原理

```
AI 客户端（Cursor / Claude Desktop）
    │  stdio — MCP 协议
    ▼
start-mcp.js                         ← 本包入口
    ├── 启动 vis-server.js            ← 私有渲染服务（:8888）
    │       └── @antv/gpt-vis-ssr    ← 将图表规格渲染为 PNG
    │               └── 图片保存到 VIS_OUTPUT_DIR
    └── 启动 @antv/mcp-server-chart（stdio 模式）
            └── 向 AI 暴露 26 个图表工具

会话结束时：
    ├── VIS_CLEANUP=true → 删除本次会话产生的所有图片
    └── 自动关闭渲染服务
```

- **首次调用**：约 5–15 秒冷启动（下载依赖 + 渲染器初始化）
- **后续调用**：即时响应（进程在会话期间保持运行）
- **会话结束**：两个进程自动清理，无残留

---

## 支持的图表类型（26 种）

| 类别 | 图表 |
|---|---|
| 趋势 | 折线图、面积图、双轴图 |
| 对比 | 柱状图、条形图、直方图 |
| 占比 | 饼图、矩形树图 |
| 分布 | 散点图、箱线图、小提琴图 |
| 流向 | 桑基图、漏斗图、网络关系图 |
| 地理 | 地区分布图、标记地图、路径地图（仅中国区域） |
| 层级 | 组织架构图、思维导图 |
| 专项 | 雷达图、水位图、词云、鱼骨图、流程图、韦恩图、表格 |

---

## 系统要求

| 环境 | 要求 |
|---|---|
| **Node.js** | >= 18.0.0 |
| **Windows** | ✅ 开箱即用 |
| **macOS** | ✅ 开箱即用 |
| **Linux** | 需安装 canvas 原生依赖：`sudo apt-get install libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev` |

---

## 版本锁定

使用指定版本（推荐生产环境）：

```json
"args": ["-y", "github:yanbober/ai-mcp-chart-vis#v1.0.0"]
```

强制更新到最新版本：

```bash
npx --force github:yanbober/ai-mcp-chart-vis --version
```

---

## 本地开发

```bash
git clone https://github.com/yanbober/ai-mcp-chart-vis.git
cd ai-mcp-chart-vis
npm install

# 仅启动渲染服务
npm run vis:start

# 启动完整链路（渲染服务 + MCP stdio）
npm start
```

---

## 使用 sample

Cursor 中丢入一个 excel 等文件，chat 输入类似如下内容：
```
洞察一下这个用户反馈 xlsx，分端帮忙通过你认为最合适的图表呈现下，同时将洞察结果图文生成 md 格式报告，要简单明了，不要长篇大论。
注意：生成的 md 中图表等图片直接同 md 文件一起放到当前项目的 result 目录，md 文件中引用图片使用本地引用。
```

打开产物 md 文件预览图文并茂效果。

其他使用场景和配合其他工具整合自行探索~

## 致谢

本项目站在以下优秀开源项目的肩膀上构建，向原作者们致敬 🙏

| 项目 | 说明 |
|---|---|
| [@antv/gpt-vis-ssr](https://github.com/antvis/GPT-Vis/tree/main/bindings/gpt-vis-ssr) | 图表服务端渲染核心，将图表规格转换为 PNG 图片 |
| [@antv/mcp-server-chart](https://github.com/antvis/mcp-server-chart) | MCP 图表工具集，向 AI 暴露 26+ 种图表生成能力 |

如果你有更多定制需求，欢迎基于上述原项目二次开发，各显神通！
原项目均遵循 MIT 协议，欢迎 Star、Fork、PR 🚀

---

## 许可证

MIT