plots-mcp

一个用于数据可视化的模型上下文协议（MCP）服务。它提供用于根据数据绘制图表（折线图、柱状图、饼图、散点图、热力图等）的工具，并以图像、Base64 文本或 Mermaid 图表的形式返回绘图结果。

为什么选择 MCP Plots？

• 使用 Mermaid 即时生成以可视化为先的图表（可直接在 Cursor 等 MCP 客户端中渲染）
• 通过简单提示词，根据纯数据生成图表
• 可通过 uvx 零配置运行，也可从 PyPI/Docker 安装
• 输出格式灵活：Mermaid（默认）、PNG 图像或文本

快速使用

• 向 MCP 客户端提出请求：“创建一个显示销售额的柱状图：A=100，B=150，C=80”
• 默认输出为 Mermaid，因此图表会立即在 Cursor 中渲染

快速入门

从 PyPI 安装（推荐）

pip install mcp-plots
mcp-plots  # Start the server

Cursor 用户

1. 安装软件包：pip install mcp-plots
2. 添加到 Cursor MCP 配置（~/.cursor/mcp.json）：

   {
     "mcpServers": {
       "plots": {
         "command": "mcp-plots",
         "args": ["--transport", "stdio"]
       }
     }
   }
   

   替代方案（通过 uvx + PyPI 零安装）：

   {
     "mcpServers": {
       "plots": {
         "command": "uvx",
         "args": ["mcp-plots", "--transport", "stdio"]
       }
     }
   }
   

3. 重启 Cursor
4. 提问：“创建一个显示销售额的柱状图：A=100，B=150，C=80”

开发环境安装

uvx --from git+https://github.com/mr901/mcp-plots.git run-server.py

文档 → | 快速入门 → | API 参考 →

MCP 注册表

此服务以 MCP 注册表标识符 io.github.MR901/mcp-plots 发布。你可以通过官方注册表 API 查找或验证它：

curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.MR901/mcp-plots"

此项目的注册表元数据记录在 server.json 中。

使用 Smithery 安装

此仓库包含用于通过 Smithery 轻松设置的 smithery.yaml。

• 文件：smithery.yaml
• 文档：https://smithery.ai/docs/config#smitheryyaml

使用 Smithery CLI 安装的示例（按需调整 --client，例如 cursor、claude）：

npx -y @smithery/cli install \
  https://raw.githubusercontent.com/mr901/mcp-plots/main/smithery.yaml \
  --client cursor

安装完成后，你的 MCP 客户端应能够使用 smithery.yaml 中定义的命令，通过 stdio 启动服务。

项目结构

src/
  app/                # Server construction and runtime
    server.py
  capabilities/       # MCP tools and prompts
    tools.py
    prompts.py
  visualization/      # Plotting engines and configurations
    chart_config.py
    generator.py

要求

• Python 3.10+
• 参见 requirements.txt

设置方式

uvx（推荐）

无需管理 Python 环境即可运行 MCP 服务的最简单方式：

# Run directly with uvx (no installation needed)
uvx --from git+https://github.com/mr901/mcp-plots.git run-server.py

# Or install and run the command
uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots

# With custom options
uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots --port 8080 --log-level DEBUG

为什么选择 uvx？

• 无需管理环境：自动处理 Python 依赖项
• 隔离执行：在独立的虚拟环境中运行
• 始终使用最新版本：从仓库拉取最新代码
• 零配置：无需通过 pip install 即可立即使用
• 跨平台：同一条命令适用于 Windows、macOS 和 Linux

PyPI（传统安装方式）

1. 安装依赖项

pip install -r requirements.txt

2. 运行服务（HTTP 传输，默认端口为 8000）

python -m src --transport streamable-http --host 0.0.0.0 --port 8000 --log-level INFO

3. 通过 stdio 运行（适用于会启动进程的 MCP 客户端）

python -m src --transport stdio

本地开发（从源代码安装）

git clone https://github.com/mr901/mcp-plots.git
cd mcp-plots
pip install -e .
python -m src --transport stdio --log-level DEBUG

Docker

docker build -t mcp-plots .
docker run -p 8000:8000 mcp-plots

环境变量（可选）：

• MCP_TRANSPORT（streamable-http|stdio）
• MCP_HOST（默认值为 0.0.0.0）
• MCP_PORT（默认值为 8000）
• LOG_LEVEL（默认值为 INFO）

工具

• list_chart_types() → 返回可用的图表类型
• list_themes() → 返回可用的主题
• suggest_fields(sample_rows) → 根据数据样本建议字段角色
• render_chart(chart_type, data, field_map, config_overrides?, options?, output_format?) → 返回 MCP 内容
• generate_test_image() → 生成测试图像（红色圆形），以验证 MCP 图像支持

Cursor 集成

此 MCP 服务完全兼容 Cursor 的图像支持！使用 render_chart 工具时：

• 图表直接显示在聊天中——无需保存文件或打开单独的窗口
• AI 可以分析图表——支持视觉的模型可以讨论并解读可视化内容
• 完美的 MCP 格式——使用 Cursor 所需的精确 Base64 PNG 格式

此服务会以 Cursor 所需的 MCP 格式返回图像：

{
  "content": [
    {
      "type": "image", 
      "data": "<base64-encoded-png>",
      "mimeType": "image/png"
    }
  ]
}

调用示例（伪代码）：

render_chart(
  chart_type="bar",
  data=[{"category":"A","value":10},{"category":"B","value":20}],
  field_map={"category_field":"category","value_field":"value"},
  config_overrides={"title":"Example Bar","width":800,"height":600,"output_format":"MCP_IMAGE"}
)

返回结构（PNG）：

{
  "status": "success",
  "content": [{"type":"image","data":"<base64>","mimeType":"image/png"}]
}

配置

可通过环境变量或命令行参数配置此服务：

服务设置

• MCP_TRANSPORT - 传输类型：streamable-http 或 stdio（默认：streamable-http）
• MCP_HOST - 主机地址（默认：0.0.0.0）
• MCP_PORT - 端口号（默认：8000）
• LOG_LEVEL - 日志级别：DEBUG、INFO、WARNING、ERROR、CRITICAL（默认：INFO）
• MCP_DEBUG - 启用调试模式：true 或 false（默认：false）

图表设置

• CHART_DEFAULT_WIDTH - 默认图表宽度（像素）（默认：800）
• CHART_DEFAULT_HEIGHT - 默认图表高度（像素）（默认：600）
• CHART_DEFAULT_DPI - 默认图表 DPI（默认：100）
• CHART_MAX_DATA_POINTS - 每张图表的最大数据点数（默认：10000）

命令行用法

使用 uvx（推荐）：

uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots --help

# Examples:
uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots --port 8080 --log-level DEBUG
uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots --chart-width 1200 --chart-height 800

传统 Python：

python -m src --help

# Examples:
python -m src --transport streamable-http --host 0.0.0.0 --port 8000
python -m src --log-level DEBUG --chart-width 1200 --chart-height 800

Docker

构建镜像：

docker build -t mcp-plots .

使用自定义配置运行容器：

docker run --rm -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  -e LOG_LEVEL=INFO \
  -e CHART_DEFAULT_WIDTH=1000 \
  -e CHART_DEFAULT_HEIGHT=700 \
  -e CHART_DEFAULT_DPI=150 \
  -e CHART_MAX_DATA_POINTS=5000 \
  mcp-plots

Cursor MCP 集成

Cursor 快速设置

Plots MCP Server 专为与 Cursor 的 MCP 支持无缝协作而设计。集成方法如下：

1. 添加到 Cursor 的 MCP 配置

将以下内容添加到 Cursor 的 MCP 配置文件（~/.cursor/mcp.json 或类似文件）中：

{
  "mcpServers": {
    "plots": {
      "command": "uvx",
      "args": [
        "--from", 
        "git+https://github.com/mr901/mcp-plots.git@main",
        "mcp-plots",
        "--transport", 
        "stdio"
      ],
      "env": {
        "LOG_LEVEL": "INFO",
        "CHART_DEFAULT_WIDTH": "800",
        "CHART_DEFAULT_HEIGHT": "600"
      }
    }
  }
}

2. 替代方案：HTTP 传输

用于基于 HTTP 的集成：

{
  "mcpServers": {
    "plots-http": {
      "command": "uvx",
      "args": [
        "--from", 
        "git+https://github.com/mr901/mcp-plots.git@main", 
        "mcp-plots",
        "--transport", 
        "streamable-http",
        "--host", 
        "127.0.0.1",
        "--port", 
        "8000"
      ]
    }
  }
}

3. 本地开发设置

用于本地开发（如果已克隆代码）：

{
  "mcpServers": {
    "plots-dev": {
      "command": "python",
      "args": ["-m", "src", "--transport", "stdio"],
      "cwd": "/path/to/mcp-plots",
      "env": {
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

4. 验证集成

添加配置后：

1. 重启 Cursor
2. 在 Cursor 的 MCP 面板中检查 MCP 连接
3. 使用简单图表进行测试：

   Create a bar chart showing sales data: A=100, B=150, C=80
   

优先使用 MERMAID 的方案

此服务默认优先使用 MERMAID 输出，因为：

• ✅ 在 Cursor 中即时渲染——无需外部查看器
• ✅ 支持交互——Cursor 可以分析并讨论这些图表
• ✅ 轻量——生成和显示速度快
• ✅ 可扩展——基于矢量，任何缩放级别下都能正常显示

支持原生 MERMAID 的图表类型：

• line、bar、pie、area → xychart-beta 格式
• histogram → 带自动分箱的 xychart-beta
• funnel → 带渐变色的样式化流程图
• gauge → 带颜色编码值指示器的流程图
• sankey → 带源/目标样式的流向图

可用工具

render_chart

以优先使用 MERMAID 的方式生成图表的主要工具。

参数：

• chart_type - 图表类型（line、bar、pie、scatter、heatmap 等）
• data - 数据对象列表
• field_map - 字段映射（x_field、y_field、category_field 等）
• config_overrides - 图表配置覆盖项
• output_format - 输出格式（mermaid [默认]、mcp_image、mcp_text）

特殊模式：

• chart_type="help" - 显示可用的图表类型和主题
• chart_type="suggest" - 分析数据并建议字段映射

configure_preferences

用于设置用户偏好的交互式配置工具。

参数：

• output_format - 默认输出格式（mermaid、mcp_image、mcp_text）
• theme - 默认主题（default、dark、seaborn、minimal）
• chart_width - 默认图表宽度（像素）
• chart_height - 默认图表高度（像素）
• reset_to_defaults - 将所有偏好重置为系统默认值

功能：

• 持久化设置 - 保存到 ~/.plots_mcp_config.json
• 实时预览 - 使用当前设置显示示例图表
• 覆盖支持 - 使用 config_overrides 进行一次性更改

文档

其他资源

• 完整文档 - 技术文档中心
• 快速入门 - 5 分钟设置指南
• 集成指南 - MCP 客户端设置与配置
• API 参考 - 完整的工具规范和示例
• 进阶指南 - 架构、部署和开发
• 示例提示词 - 可直接使用的测试示例

图表示例

基础柱状图：

{
  "chart_type": "bar",
  "data": [
    {"category": "Sales", "value": 120},
    {"category": "Marketing", "value": 80},
    {"category": "Support", "value": 60}
  ],
  "field_map": {
    "category_field": "category", 
    "value_field": "value"
  }
}

时间序列折线图：

{
  "chart_type": "line",
  "data": [
    {"date": "2024-01", "revenue": 1000},
    {"date": "2024-02", "revenue": 1200},
    {"date": "2024-03", "revenue": 1100}
  ],
  "field_map": {
    "x_field": "date",
    "y_field": "revenue"
  }
}

漏斗图：

{
  "chart_type": "funnel",
  "data": [
    {"stage": "Awareness", "value": 1000},
    {"stage": "Interest", "value": 500}, 
    {"stage": "Purchase", "value": 100}
  ],
  "field_map": {
    "category_field": "stage",
    "value_field": "value"
  }
}

🔧 配置

环境变量

• MCP_TRANSPORT - 传输类型（streamable-http | stdio）
• MCP_HOST - 主机地址（默认：0.0.0.0）
• MCP_PORT - 端口号（默认：8000）
• LOG_LEVEL - 日志级别（默认：INFO）
• MCP_DEBUG - 启用调试模式（true | false）
• CHART_DEFAULT_WIDTH - 默认图表宽度（像素）（默认：800）
• CHART_DEFAULT_HEIGHT - 默认图表高度（像素）（默认：600）
• CHART_DEFAULT_DPI - 默认图表 DPI（默认：100）
• CHART_MAX_DATA_POINTS - 每张图表的最大数据点数（默认：10000）

用户偏好

个人偏好存储在 ~/.plots_mcp_config.json 中：

{
  "defaults": {
    "output_format": "mermaid",
    "theme": "default",
    "chart_width": 800,
    "chart_height": 600
  },
  "user_preferences": {
    "output_format": "mcp_image",
    "theme": "dark"
  }
}

🚀 高级用法

自定义主题

可用主题：default、dark、seaborn、minimal、whitegrid、darkgrid、ticks

高分辨率图表

uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots \
  --chart-width 1920 \
  --chart-height 1080 \
  --chart-dpi 300

性能优化

• 使用 max_data_points 限制大型数据集
• MERMAID 输出最适合快速可视化，速度最快
• PNG 输出适用于高质量静态图像
• SVG 输出适用于可缩放矢量图形

🐛 故障排除

常见问题

问题：图表无法在 Cursor 中渲染

• 解决方案：确保 output_format="mermaid"（默认值）
• 检查：Cursor 中的 MCP 服务连接

问题：找不到 uvx 命令

• 解决方案：安装 uv：curl -LsSf https://astral.sh/uv/install.sh | sh

问题：端口已被占用

• 解决方案：使用其他端口：--port 8001

问题：大型数据集导致速度变慢

• 解决方案：对数据采样，或增大 --max-data-points

调试模式

uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots \
  --debug \
  --log-level DEBUG

📝 说明

• Matplotlib 在容器中以无头模式（Agg 后端）运行
• 对于大型数据集，请对数据采样以保持响应速度
• 可通过 config_overrides 按请求覆盖图表默认设置
• MERMAID 图表可在 Cursor 中即时渲染，带来最佳用户体验
• 用户偏好会在不同会话间保留，并默认应用于所有图表