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 中即時渲染，提供最佳用戶體驗。
• 用戶偏好跨會話持久化，默認應用於所有圖表。