Plotnine MCP

🚀 Plotnine MCP Server

📊 Plotnine MCP Server 是一個基於 Model Context Protocol (MCP) 的服務器，它藉助 plotnine 將 R 語言中廣受歡迎的 ggplot2 圖形語法引入 Python，讓你能夠通過自然語言，利用 AI 實現數據可視化。通過與 AI 聊天，你可以輕鬆創建出達到出版級質量的統計圖形。這個模塊化的 MCP 服務器允許 Claude 等 AI 助手通過圖形語法範式組合圖層，生成高度可定製的可視化效果。

✨ 主要特性

核心可視化功能

• 🎨 多層繪圖：在單個圖表中組合多種幾何圖形（如散點圖 + 趨勢線、箱線圖 + 抖動點等）。
• 圖形語法：運用美學、幾何圖形、比例尺、主題、分面和座標等元素來構建圖表。
• 20 多種幾何圖形類型：包括點、線、條形圖、直方圖、箱線圖、小提琴圖等。
• 多數據源支持：可從文件（CSV、JSON、Parquet、Excel）、URL 或內聯 JSON 加載數據。
• 多輸出格式：支持 PNG、PDF、SVG 格式，且可配置尺寸和 DPI。

智能特性（新功能！）

• 📋 9 種繪圖模板：為常見模式（時間序列、帶趨勢的散點圖、分佈比較等）提供預配置模板。
• 🤖 AI 模板建議：分析你的數據並推薦合適的圖表類型。
• 🎨 21 種調色板：包含色盲友好、科學、分類、企業、順序和發散等多種調色板。
• 📊 數據預覽：在繪圖前檢查數據並提供全面摘要。
• 🎯 智能錯誤信息：通過模糊匹配為列名、幾何類型和主題中的拼寫錯誤提供修正建議。
• 💾 配置導出/導入：將繪圖配置保存為 JSON 文件，以便重複使用。

數據處理（新功能！）

• 🔄 12 種數據轉換：包括過濾、分組彙總、排序、選擇、重命名、變異、刪除缺失值、填充缺失值、採樣、去重、滾動計算、透視等。
• ⚡ 批量處理：一次操作創建多個圖表。
• 🔗 鏈式轉換：按順序應用多個轉換。

主題與定製

• 靈活的主題設置：內置主題，提供豐富的自定義選項。
• 統計轉換：添加平滑、分箱、密度估計和彙總等功能。
• 分面繪圖：使用包裝或網格佈局按分類變量拆分圖表。

📦 安裝指南

1. 克隆或下載本倉庫

cd plotnine-mcp

2. 安裝依賴

使用 pip 安裝：

pip install -e .

若需要完整功能（支持 Parquet 和 Excel）：

pip install -e ".[full]"

3. 配置 MCP 客戶端

查找安裝路徑

首先，找到 plotnine-mcp 命令的安裝位置：

which plotnine-mcp

這將顯示類似 /path/to/python/bin/plotnine-mcp 的路徑。在以下配置中使用此完整路徑。

Claude Desktop

將服務器添加到 Claude Desktop 配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

推薦（使用入口點）：

{
  "mcpServers": {
    "plotnine": {
      "command": "/path/to/your/python/bin/plotnine-mcp",
      "args": []
    }
  }
}

替代方法（使用 python -m）：

{
  "mcpServers": {
    "plotnine": {
      "command": "python",
      "args": ["-m", "plotnine_mcp.server"]
    }
  }
}

如果你在虛擬環境中安裝，請替換為完整路徑：

{
  "mcpServers": {
    "plotnine": {
      "command": "/path/to/venv/bin/plotnine-mcp",
      "args": []
    }
  }
}

Cursor

推薦方法：通過項目中的 .cursor/mcp.json 進行配置：

{
  "mcpServers": {
    "plotnine": {
      "command": "/path/to/your/python/bin/plotnine-mcp",
      "args": []
    }
  }
}

替代方法：打開命令面板 (Cmd/Ctrl+Shift+P) 並搜索 "Preferences: Open User Settings (JSON)"，添加到 Cursor 全局設置中：

{
  "mcp.servers": {
    "plotnine": {
      "command": "/path/to/your/python/bin/plotnine-mcp",
      "args": []
    }
  }
}

使用 python -m 的替代方法：

{
  "mcpServers": {
    "plotnine": {
      "command": "python",
      "args": ["-m", "plotnine_mcp.server"]
    }
  }
}

VSCode（使用 Cline/Roo-Cline）

添加到 VSCode MCP 設置文件中：

• macOS/Linux：~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
• Windows：%APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json

{
  "mcpServers": {
    "plotnine": {
      "command": "/path/to/your/python/bin/plotnine-mcp",
      "args": []
    }
  }
}

對於 VSCode 中的其他 MCP 客戶端，請參考其特定文檔進行 MCP 服務器配置。

4. 重啟應用程序

重啟 Claude Desktop、Cursor 或 VSCode 以使更改生效。此時，plotnine MCP 服務器應該可用了！

💻 使用示例

基礎示例

Create a scatter plot from data.csv with x=age and y=height

高級示例

Create a line plot from sales_data.csv showing:
- x: date, y: revenue, color by region
- Use a minimal theme with figure size 12x6
- Add a smooth trend line
- Facet by product category
- Label the plot "Q4 Sales Performance"
- Save as PDF

可用工具（共 11 種）

核心工具

create_plot

創建完全可定製的 plotnine 可視化圖表。

必需參數：

• data_source：數據源配置
• aes：美學映射（列名）
• geom 或 geoms：幾何圖形規範

可選參數：

• scales：比例尺配置數組
• theme：主題配置
• facets：分面配置
• labels：圖表標籤（標題、x 軸、y 軸、圖例、副標題）
• coords：座標系配置
• stats：統計轉換
• transforms：數據轉換（新功能！）
• output：輸出配置（格式、大小、DPI、目錄）

list_geom_types

列出所有 20 多種可用的幾何圖形類型及其描述。

數據工具（新功能！）

preview_data

在創建圖表前預覽和檢查數據。返回數據集形狀、列類型、前幾行、統計信息和缺失值。

參數：

• data_source：數據源配置
• rows：預覽的行數（默認值：5）

模板工具（新功能！）

list_plot_templates

列出所有 9 種可用的繪圖模板及其描述：

• time_series
• scatter_with_trend
• distribution_comparison
• category_breakdown
• correlation_heatmap
• boxplot_comparison
• multi_line
• histogram_with_density
• before_after

create_plot_from_template

使用預定義模板創建圖表。只需提供數據和美學映射，模板將處理其餘部分。

參數：

• template_name：模板名稱
• data_source：數據源配置
• aes：美學映射
• labels：可選標籤
• output：可選輸出配置
• overrides：可選的模板設置覆蓋項

樣式工具（新功能！）

list_themes

列出所有可用的圖表主題及其描述和自定義選項。

list_color_palettes

列出 6 個類別中的 21 種調色板：

• 色盲友好（3 種調色板）
• 科學（4 種調色板）
• 分類（4 種調色板）
• 企業（3 種調色板）
• 順序（4 種調色板）
• 發散（3 種調色板）

參數：

• category：可選的類別過濾器

配置工具

export_plot_config

將繪圖配置導出為 JSON 文件，以便重複使用和共享。

參數：

• config：要導出的繪圖配置
• filename：輸出文件名
• directory：輸出目錄（默認值：./plot_configs）

import_plot_config

導入並使用保存的繪圖配置，可選擇覆蓋部分參數。

參數：

• config_path：保存的配置文件路徑
• overrides：可選的參數覆蓋項

批量工具（新功能！）

batch_create_plots

一次操作創建多個圖表。非常適合為所有列、成對比較或同一數據的不同可視化生成圖表。

參數：

• plots：繪圖配置數組

幾何圖形類型

• point：散點圖點
• line：連接點的折線圖
• bar：條形圖（默認計數）
• col：柱狀圖（恆等統計）
• histogram：連續數據的直方圖
• boxplot：箱線圖
• violin：小提琴圖
• area：折線下方的填充區域
• density：核密度圖
• smooth：平滑條件均值
• jitter：抖動點（減少重疊）
• tile：熱力圖/瓦片圖
• text：文本註釋
• errorbar：誤差線
• hline/vline/abline：參考線
• path：按順序連接點的路徑
• polygon：填充多邊形
• ribbon：區間帶

示例

簡單散點圖

{
  "data_source": {
    "type": "file",
    "path": "./data/iris.csv"
  },
  "aes": {
    "x": "sepal_length",
    "y": "sepal_width",
    "color": "species"
  },
  "geom": {
    "type": "point",
    "params": {"size": 3, "alpha": 0.7}
  }
}

帶主題的折線圖

{
  "data_source": {
    "type": "url",
    "path": "https://example.com/timeseries.csv"
  },
  "aes": {
    "x": "date",
    "y": "value",
    "color": "category"
  },
  "geom": {
    "type": "line",
    "params": {"size": 1.5}
  },
  "scales": [
    {
      "aesthetic": "x",
      "type": "datetime",
      "params": {"date_breaks": "1 month"}
    }
  ],
  "theme": {
    "base": "minimal",
    "customizations": {
      "figure_size": [12, 6],
      "legend_position": "bottom"
    }
  },
  "labels": {
    "title": "Time Series Analysis",
    "x": "Date",
    "y": "Value"
  }
}

分面箱線圖

{
  "data_source": {
    "type": "inline",
    "data": [
      {"group": "A", "category": "X", "value": 10},
      {"group": "A", "category": "Y", "value": 15},
      {"group": "B", "category": "X", "value": 12}
    ]
  },
  "aes": {
    "x": "group",
    "y": "value",
    "fill": "group"
  },
  "geom": {
    "type": "boxplot"
  },
  "facets": {
    "type": "wrap",
    "facets": "~ category"
  },
  "theme": {
    "base": "bw"
  }
}

多層繪圖：散點圖 + 平滑趨勢線

新功能！ 組合多個幾何圖形創建複雜的可視化圖表：

{
  "data_source": {
    "type": "file",
    "path": "./data/measurements.csv"
  },
  "aes": {
    "x": "time",
    "y": "value",
    "color": "sensor"
  },
  "geoms": [
    {
      "type": "point",
      "params": {"size": 2, "alpha": 0.6}
    },
    {
      "type": "smooth",
      "params": {"method": "lm", "se": false}
    }
  ],
  "theme": {
    "base": "minimal",
    "customizations": {"figure_size": [12, 6]}
  },
  "labels": {
    "title": "Sensor Readings with Trend Lines",
    "x": "Time",
    "y": "Measurement"
  }
}

帶抖動點的箱線圖

同時顯示分佈摘要和單個數據點：

{
  "data_source": {
    "type": "file",
    "path": "./data/experiment.csv"
  },
  "aes": {
    "x": "treatment",
    "y": "response",
    "fill": "treatment"
  },
  "geoms": [
    {
      "type": "boxplot",
      "params": {"alpha": 0.7}
    },
    {
      "type": "jitter",
      "params": {"width": 0.2, "alpha": 0.5, "size": 1}
    }
  ],
  "theme": {
    "base": "bw"
  },
  "labels": {
    "title": "Treatment Effects with Individual Observations"
  }
}

聊天示例

你可以通過自然語言創建圖表：

• "Create a histogram of the 'age' column from users.csv"
• "Make a scatter plot with smooth trend line showing price vs size, colored by category"
• "Plot a line chart from sales.csv with date on x-axis and revenue on y-axis, faceted by region, using a dark theme"
• "Create a violin plot comparing distributions of test scores across different schools"
• "Make a boxplot with individual points overlaid showing temperature by season"
• "Create a scatter plot with a linear trend line for each category, showing the relationship between hours studied and test scores"

使用新工具

• "Preview the data from sales.csv before plotting"
• "What themes are available?"
• "Show me all available plot templates"
• "Suggest appropriate plot types for my data"
• "Create a time series plot using the template"
• "List color palettes in the scientific category"
• "Export this plot configuration so I can reuse it later"
• "Load the plot config from my_config.json and use it with a different dataset"
• "Create a plot from the saved configuration but change the theme to minimal"
• "Create plots for each category in my dataset"（批量處理）
• "Filter the data to show only active users, then create a histogram"（數據轉換）

新示例

使用模板

使用模板創建帶趨勢線的散點圖：

"Use the scatter_with_trend template to plot height vs weight from my data"

這將自動創建一個包含以下元素的圖表：

• 散點（帶透明度）
• 線性迴歸線
• 置信區間
• 簡約主題

使用調色板

"Create a bar chart colored using the colorblind-safe Okabe-Ito palette"

數據轉換

"Filter sales data to show only Q4, group by region, sum the revenue, and create a bar chart"

這將在繪圖前應用以下轉換：

1. 過濾："quarter == 'Q4'"
2. 分組彙總：按地區分組，彙總收入
3. 繪圖：結果的條形圖

批量處理

"Create histogram plots for all numeric columns in my dataset"

配置選項

主題

可用的基礎主題：

• gray（默認）
• bw（黑白）
• minimal
• classic
• dark
• light
• void

比例尺類型

• 位置：連續、離散、對數 10、平方根、日期時間
• 顏色/填充：漸變、離散、Brewer

座標系

• cartesian（默認）
• flip（交換 x 軸和 y 軸）
• fixed（固定縱橫比）
• trans（轉換後的座標）

輸出

默認情況下，圖表將保存到 ./output 目錄，以 PNG 文件形式保存，DPI 為 300。你可以自定義：

• format：png、pdf、svg
• filename：自定義文件名（默認自動生成）
• width/height：尺寸（英寸）
• dpi：光柵格式的分辨率
• directory：輸出目錄路徑

故障排除

"Module not found" 錯誤

確保你已安裝該包：

pip install -e .

Parquet/Excel 支持

安裝可選依賴：

pip install -e ".[full]"

"Cannot find data file"

使用絕對路徑或相對於 Claude Desktop 運行位置的相對路徑。

圖表未渲染

檢查以下內容：

• aes 中的列名與數據匹配
• 數據類型適合幾何圖形
• 提供了必需的美學映射（例如，大多數幾何圖形需要 x 和 y）

開發

運行測試

pytest

代碼格式化

black src/
ruff check src/

📄 許可證

MIT

貢獻

歡迎貢獻！請提交問題或拉取請求。

資源

• plotnine 文檔
• MCP 規範
• 圖形語法