MCP Plots

🚀 Plots MCP Server

このサーバーは、データ可視化用のModel Context Protocol (MCP) サーバーです。データからチャート（折れ線グラフ、棒グラフ、円グラフ、散布図、ヒートマップなど）をレンダリングするツールを公開し、チャートを画像、Base64テキスト、またはMermaid図として返します。

✨ 主な機能

• Mermaidを使用した即時のビジュアルファーストなチャート（CursorなどのMCPクライアントで直接レンダリング）
• 単純なデータからチャートを生成するためのシンプルなプロンプト
• uvxを介したゼロセットアップオプション、またはPyPI/Dockerからのインストール
• 柔軟な出力形式: mermaid（デフォルト）、PNG画像、またはテキスト

🚀 クイックスタート

クイック使用法

• MCPクライアントに「売上を示す棒グラフを作成してください: A=100, B=150, C=80」と依頼します。
• デフォルトの出力はMermaidなので、図はCursor内で即座にレンダリングされます。

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. 「売上を示す棒グラフを作成してください: 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.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

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)

💻 使用例

基本的な使用法

このサーバーが提供するツールを使用すると、簡単にチャートを生成できます。例えば、以下のようにMCPクライアントに依頼することができます。

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

高度な使用法

以下のコマンドを使用すると、高解像度のチャートを生成できます。

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

📚 ドキュメント

追加リソース

• 完全なドキュメント - 技術的なドキュメントのハブ
• クイックスタート - 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パネルで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内で即座にレンダリングされ、最高のユーザー体験を提供します。
• ユーザー設定はセッションをまたいで保持され、デフォルトですべてのチャートに適用されます。