Skip to main content
Glama
deenesjakoruzh
shyinlim

Mindmup2GoogleDriveMCP

by shyinlim
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

MindMup2 Google Drive MCP サーバー

AIクライアント（Claude Code、Cursor）が、Googleドライブに保存された MindMup 2 の .mup マインドマップを検索、読み取り、詳細確認できる Model Context Protocol (MCP) サーバーです。3MBのJSONツリーをモデルに丸ごと渡す必要はありません。大きなマップは自動的にツリーアウトラインに要約され、AIは node_path を使用して特定のセクションを掘り下げることができます。

互換性: Claude Code、Cursor (HTTPトランスポート)。 非対応: Claude Desktop (stdioのみ)。

💫 結果

ezgif-5b4a0eb3a275f8.gif

Related MCP server: Google-Workspace-MCP-Server

✨ 機能

  • Googleドライブ全体でのMindMupファイルの検索（読み取り専用）

  • 大きなマインドマップのためのツリーナビゲーションとセクションのドリルダウン機能 — 小さなファイルは全コンテンツを返し、大きなファイルはドリルダウン可能なアウトラインを返します

  • X-Client-Id ヘッダーによるクライアントごとのキャッシュ分離 — ユーザーやツール間でキャッシュされたコンテンツが共有されません

  • fastmcp run --reload とバインドマウントされたソースによるホットリロード開発モード

  • /health および /ping エンドポイントを備えた FastMCP サーバー

  • 開発および本番環境用の Docker Compose

🗺️ エンドツーエンドの流れ

1. Set up Google Cloud service account     →  download JSON key
2. Share your Drive folder with the SA     →  Viewer access
3. Base64-encode the JSON key              →  for X-Google-Credential header
4. Run the server  (Docker or Python)      →  http://127.0.0.1:9805
5. Configure your MCP client (Claude/Cursor) with the base64 credential
6. Verify  →  curl http://127.0.0.1:9805/health

🔧 利用可能なMCPツール

ツール

説明

list_files

GoogleドライブからMindMupファイルを一覧表示します（デフォルトではフォルダおよび .mup 以外のファイルは除外されます）。id、name、folder_url、size、modified_time を返します。

read_mindmap

file_id または file_name でMindMupファイルを読み取ります（いずれかが必須。名前の場合は最初の一致を使用）。小さなファイル（100KB未満）は content_type: "full" を返します。大きなファイルは tree_outline、section_stats、suggested_start_paths を含む content_type: "outline_only" を返します。

search_mindmap

キーワードでノードを検索します。パラメータ: file_id、keyword、オプションの node_path（サブツリー範囲）、max_results=30、normalize_whitespace=True。node_path、title_preview、breadcrumb、children_count を含むノードを返します。

get_mindmap_section

node_path（ドット区切りの整数、ルートは 1、例: "1.2.3"）でセクションを掘り下げます。オプションの max_depth、offset=0、limit=0。`content_type: "full"

"outline_only"

"paginated"

"truncated"` を返します — セクションがまだ大きすぎる場合は自動的に切り替わります。

AIエージェント向けの推奨ワークフロー: list_files → read_mindmap → outline_only の場合、search_mindmap（キーワード検索）または get_mindmap_section（suggested_start_paths からの node_path を使用）を実行します。

🚀 はじめに

前提条件

  • Python 3.12+

  • Docker & docker-compose (make run-dev-docker / make run-prod に必要) ; 参照: makefile

  • Google Cloud Platform アカウント

  • HTTPトランスポートをサポートするMCPクライアント（Claude Code または Cursor）

Google Drive API のセットアップ

ステップ

説明

画像

1

Google Cloud Console にアクセスし、新しいプロジェクトを作成します（無料枠で十分です。Drive APIに課金は不要です）。

2

Google Drive API を有効にします。

3

サービスアカウントの認証情報を作成します:- 「IAMと管理」→「サービスアカウント」→「サービスアカウントを作成」- プロジェクトレベルのロールは不要（ドライブの共有設定で認証を管理）- 作成したSAを開く → 「キー」タブ → 「鍵を追加」 → JSON → キーファイルをダウンロード。

google_service_acc.jpg

4

JSONキーファイル全体をBase64エンコードします（ヘッダーリファレンスを参照）。⚠️ JSONファイルを .gitignore に追加してください — 絶対にコミットしないでください。

5

GoogleドライブのフォルダをSAと共有します:- JSONから client_email の値をコピー- フォルダを右クリック → 共有 → メールアドレスを貼り付け- 閲覧者権限を付与し、「通知」のチェックを外す- 共有設定はサブフォルダにも継承されます。

google_drive_share_list2.jpg

スコープに関する注意: サーバーは auth/drive + auth/drive.file を要求します。広範なスコープに見えますが、フォルダレベルの「閲覧者」共有により、SAは共有されたものしか読み取れません。ワークスペース管理アカウントでは外部共有がブロックされる場合があります。その場合は、管理者にドメインのサービスアカウント共有を許可するよう依頼してください。

サーバーの実行

Docker (推奨):

make run-dev-docker   # dev: hot-reload, source bind-mounted
make run-prod         # prod: no reload

直接Python (Dockerなし):

pip install -r requirements.txt
python3 run.py
# Optionally: MCP_TRANSPORT=streamable-http python3 run.py

サーバーの検証

curl http://127.0.0.1:9805/health
# => {"result":"success","time":"...","message":"MCP server is running. ..."}

success が返されない場合は、docker logs <container>（Dockerモード）または標準出力（Pythonモード）を確認してください。

テストの実行

pip install -r requirements.txt
pytest

MCPクライアントの設定

MCPクライアントの設定（Claude Codeの場合は ~/.claude/mcp.json、またはCursorのMCP設定）に追加します:

{
    "mcpServers": {
        "mindmup-gdrive": {
            "type": "http",
            "url": "http://127.0.0.1:9805/mcp",
            "headers": {
                "X-Google-Credential": "ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VuXXXXXXXXXXX",
                "X-Client-Id": "shyin-claude-code"
            }
        }
    }
}

ヘッダーリファレンス

ヘッダー

必須

説明

X-Google-Credential

✅

Base64エンコードされたサービスアカウントJSON。base64encode.org を使用して出力を貼り付けてください。⚠️ Base64は エンコードであり暗号化ではありません — MCPクライアントの設定はディスク上にプレーンテキストで保存されるため、公開リポジトリや暗号化されていないクラウドバックアップには同期しないでください。

X-Client-Id

オプション

ユーザーとツールごとの一意の識別子（例: shyin-claude-code）。キャッシュキー (X-Client-Id, credential_hash, file_id) の一部として使用され、クライアント間でキャッシュされたコンテンツを分離します。省略した場合は default にフォールバックされ（他の未設定クライアントとキャッシュが共有される可能性があります）、警告がログに記録されます。推奨形式: <your-name>-<tool-name>。他のユーザーとの衝突を避けるため、エントロピーの高い値を使用してください。

🩺 トラブルシューティング

症状

考えられる原因 / 解決策

health が何も返さない / 接続拒否

サーバーが実行されていません。docker ps または標準出力を確認してください。ポート 9805 が既に使用されていませんか？ mcp_deployment/docker-compose-dev.yml を編集して再マッピングしてください。

Google Drive authentication failed

Base64が無効です。確認方法: `echo "$CRED"

base64 -d

jq .client_email` — SAのメールアドレスが表示されるはずです。

list_files が空を返す

(a) フォルダが間違ったメールアドレスと共有されています — JSON内の client_email と一致する必要があります。(b) ファイルが .mup ではありません — mindmup_only=False を指定して呼び出し、可視性を確認してください。(c) ワークスペースの組織ポリシーが外部共有をブロックしています。

Dockerビルドが失敗する

Dockerデーモンが実行されていることを確認してください。make run-dev-docker を再実行してください。

開発環境で変更が反映されない

ホットリロードはPythonソースのみを監視します。依存関係や環境変数の変更後はコンテナを再起動してください。

🏗️ プロジェクト構造

├── mcp_deployment/
│   ├── docker-compose-dev.yml
│   ├── docker-compose-prod.yml
│   └── Dockerfile
├── src/
│   ├── core/
│   │   ├── gdrive_client.py    # Google Drive API client
│   │   ├── gdrive_feature.py   # Google Drive feature implementation
│   │   ├── mcp_server.py       # Main MCP server with read tools
│   │   └── mindmup_parser.py   # MindMup parsing + tree navigation
│   ├── model/
│   │   ├── common_model.py     # Common data models
│   │   ├── gdrive_model.py     # Google Drive data models
│   │   └── mindmup_model.py    # Mind map data models (with to_ai_dict)
│   └── utility/
│       ├── enum.py             # Enumerations and constants
│       └── logger.py           # Logging utilities
├── tests/                      # Unit tests
├── plans/                      # Implementation plans
├── run.py                      # Main entry point
├── requirements.txt            # Python dependencies
└── makefile                    # Build and deployment commands

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Google-Workspace-MCP-Server

    giuseppe-coco
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server that seamlessly interacts with your Google Calendar, Gmail, Drive and so on.
    30
    MIT

  • manus-mcp

    mitjaeichhorn
    F
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that enables interaction with Google Drive through the Google Cloud API. It allows users to list, read, and upload files directly from MCP-compatible clients like manus.im or Cursor.
    -

  • mcp-server-drive

    apercura
    F
    license
    Not graded
    quality
    C
    maintenance
    A read-only Google Drive MCP server that allows searching files, reading file content (with auto-export for Google Docs, Sheets, Slides), and retrieving file metadata via OAuth authentication.
    8 npm
    2
    -