Plotnine MCP

🚀 Plotnine MCP Server

Model Context Protocol (MCP)サーバーで、plotnineを通じてggplot2のグラフ文法をPythonに持ち込み、自然言語によるAI駆動のデータ可視化を可能にします。

Rで愛用されているggplot2をPythonで実装したplotnineを使って、チャットで公開可能な品質の統計グラフを作成できます。このモジュール型の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：テンプレート設定のオーバーライド

suggest_plot_templates

データを分析し、列のタイプとオプションの目標に基づいて、AIによるプロットの提案を取得します。

パラメーター：

• data_source：分析するデータソース
• goal：オプションの目標（例：「分布を比較する」、「トレンドを表示する」）

スタイルツール（新機能！）

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": {