Mindmup2 Google Drive

A Model Context Protocol (MCP) server that lets AI clients (Claude Code, Cursor) search, read, and drill into MindMup 2 .mup mind maps stored in Google Drive — without dumping a 3MB JSON tree into the model. Large maps are auto-summarised into a tree outline; the AI then drills into specific sections by node_path.

Compatibility: Claude Code, Cursor (HTTP transport). Not supported: Claude Desktop (stdio-only).

💫 Result

✨ Features

• Search MindMup files across your entire Google Drive (read-only)
• Tree navigation + section drill-down for large mind maps — small files return full content, large files return an outline you can drill into
• Per-client cache isolation via X-Client-Id header, so different users/tools don't share cached content
• Hot-reload dev mode via fastmcp run --reload + bind-mounted source
• FastMCP server with built-in /health and /ping endpoints
• Docker Compose for both dev and prod

🗺️ End-to-End Flow

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

🔧 Available MCP Tools

Suggested workflow for AI agents: list_files → read_mindmap → if outline_only, either search_mindmap (by keyword) or get_mindmap_section (by node_path from suggested_start_paths).

🚀 Getting Started

Prerequisites

• Python 3.12+
• Docker & docker-compose (required for make run-dev-docker / make run-prod) ; Ref. makefile
• Google Cloud Platform account
• An MCP client that supports HTTP transport (Claude Code or Cursor)

Google Drive API Setup

Step	Description	Image
1	Go to Google Cloud Console and create a new project (free tier is fine — no billing required for Drive API).
2	Enable the Google Drive API.
3	Create Service Account credentials: - "IAM & Admin" → "Service Accounts" → "Create Service Account" - No project-level role needed (Drive sharing handles auth) - Open the SA → "Keys" tab → "Add Key" → JSON → download the key file.
4	Base64-encode the entire JSON key file (see Header Reference). ⚠️ Add the JSON file to .gitignore — never commit it.
5	Share your Google Drive folder with the SA: - Copy the client_email value from the JSON - Right-click the folder → Share → paste the email - Grant Viewer access, uncheck "Notify people" - Sharing propagates to subfolders.

Note on scopes: The server requests auth/drive + auth/drive.file. Despite the broad scope, with Viewer folder-level sharing the SA can only read what you've shared. Workspace-managed accounts may block external sharing — if so, ask your admin to allow service-account sharing for your domain.

Run the Server

Docker (recommended):

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

Direct Python (no Docker):

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

Verify the Server

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

If you don't get success, check docker logs <container> (Docker mode) or stdout (Python mode).

Run Tests

pip install -r requirements.txt
pytest

MCP Client Configuration

Add to your MCP client config (~/.claude/mcp.json for Claude Code, or your Cursor MCP settings):

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

Header Reference

🩺 Troubleshooting

🏗️ Project Structure

├── 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