MCP Plots

🚀 Plots MCP Server

Plots MCP Server 是一个用于数据可视化的模型上下文协议（MCP）服务器。它提供了从数据渲染图表（如折线图、柱状图、饼图、散点图、热力图等）的工具，并将图表以图像、Base64 文本或 Mermaid 图表的形式返回。

✨ 主要特性

• 即时可视化：使用 Mermaid 实现即时、以视觉为先的图表（可直接在 Cursor 等 MCP 客户端中渲染）。
• 简单提示：通过简单的提示即可从普通数据生成图表。
• 零设置选项：可通过 uvx 实现零设置，也可从 PyPI 或 Docker 进行安装。
• 灵活输出格式：支持 Mermaid（默认）、PNG 图像或文本等多种输出格式。

🚀 快速开始

📦 安装指南

PyPI 安装（推荐）

pip install mcp-plots
mcp-plots  # 启动服务器

针对 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. 输入提示："Create a bar chart showing sales: A=100, B=150, C=80"

开发环境安装

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

💻 使用示例

基础用法

向 MCP 客户端输入："Create a bar chart showing sales: A=100, B=150, C=80"，默认输出为 Mermaid 格式，图表将在 Cursor 中即时渲染。

高级用法

可根据不同的需求调整配置，如指定端口、日志级别、图表尺寸等。

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

📚 详细文档

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

🔧 技术细节

MCP 注册表

该服务器在 MCP 注册表中的标识符为 io.github.MR901/mcp-plots。可通过官方注册表 API 进行发现和验证：

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

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

项目结构

src/
  app/                # 服务器构建和运行时
    server.py
  capabilities/       # MCP 工具和提示
    tools.py
    prompts.py
  visualization/      # 绘图引擎和配置
    chart_config.py
    generator.py

要求

• Python 3.10+
• 具体依赖请参考 requirements.txt

启动方式

uvx（推荐）

无需管理 Python 环境即可运行 MCP 服务器：

# 直接使用 uvx 运行（无需安装）
uvx --from git+https://github.com/mr901/mcp-plots.git run-server.py

# 或者安装并运行命令
uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots

# 自定义选项
uvx --from git+https://github.com/mr901/mcp-plots.git mcp-plots --port 8080 --log-level DEBUG

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. 使用标准输入输出运行（适用于生成进程的 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

# 示例：
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

# 示例：
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 集成

快速设置

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 对每个请求的图表默认设置进行覆盖。

🚀 高级用法

自定义主题

可用主题：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 中即时渲染，提供最佳用户体验。
• 用户偏好跨会话持久化，默认应用于所有图表。