Skip to main content
Glama
deenesjakoruzh
shyinlim

Mindmup2GoogleDriveMCP

by shyinlim
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

MindMup2 Google Drive MCP 服务器

一个模型上下文协议 (MCP) 服务器，允许 AI 客户端（Claude Code、Cursor）搜索、读取并深入查看存储在 Google Drive 中的 MindMup 2 .mup 思维导图 —— 无需将 3MB 的 JSON 树转储给模型。大型导图会自动汇总为树状大纲；AI 随后可以通过 node_path 深入查看特定部分。

兼容性： Claude Code、Cursor (HTTP 传输)。 不支持： Claude Desktop (仅限 stdio)。

💫 结果

ezgif-5b4a0eb3a275f8.gif

Related MCP server: Google-Workspace-MCP-Server

✨ 功能

  • 搜索 MindMup 文件：跨整个 Google Drive（只读）

  • 树状导航 + 分段深入查看：针对大型思维导图 —— 小型文件返回完整内容，大型文件返回可深入查看的大纲

  • 客户端缓存隔离：通过 X-Client-Id 标头实现，确保不同用户/工具不会共享缓存内容

  • 热重载开发模式：通过 fastmcp run --reload + 绑定挂载源码实现

  • FastMCP 服务器：内置 /health 和 /ping 端点

  • 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 Drive 中的 MindMup 文件（默认过滤掉文件夹和非 .mup 文件）。返回 id、name、folder_url、size、modified_time。

read_mindmap

通过 file_id 或 file_name 读取 MindMup 文件（二选一；名称使用第一个部分匹配项）。小型文件（<100KB AI 字典）返回 content_type: "full"。大型文件返回 content_type: "outline_only"，包含 tree_outline、section_stats 和 suggested_start_paths。

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 & 管理” → “服务账户” → “创建服务账户”- 无需项目级角色（Drive 共享处理授权）- 打开服务账户 → “密钥”选项卡 → “添加密钥” → JSON → 下载密钥文件。

google_service_acc.jpg

4

对整个 JSON 密钥文件进行 Base64 编码（参见 标头参考）。⚠️ 将 JSON 文件添加到 .gitignore —— 切勿提交它。

5

将您的 Google Drive 文件夹共享给该服务账户：- 从 JSON 中复制 client_email 值- 右键点击文件夹 → 共享 → 粘贴电子邮件- 授予 查看者 权限，取消勾选 “通知人员”- 共享权限会传播到子文件夹。

google_drive_share_list2.jpg

关于作用域的说明： 服务器请求 auth/drive + auth/drive.file。尽管作用域较广，但通过文件夹级别的“查看者”共享，服务账户只能读取您共享的内容。工作区管理账户可能会阻止外部共享 —— 如果是这样，请联系您的管理员允许为您的域使用服务账户共享。

运行服务器

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

✅

您的服务账户 JSON，Base64 编码。使用 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` —— 应打印服务账户电子邮件。

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
    -