MindmupGoogleDriveMcp

MindMup2 Google Drive MCP Server

Um servidor Model Context Protocol (MCP) que permite que clientes de IA (Claude Code, Cursor) pesquisem, leiam e explorem MindMup 2 .mup mapas mentais armazenados no Google Drive — sem despejar uma árvore JSON de 3MB no modelo. Mapas grandes são automaticamente resumidos em um esboço de árvore; a IA então explora seções específicas por node_path.

Compatibilidade: Claude Code, Cursor (transporte HTTP). Não suportado: Claude Desktop (somente stdio).

💫 Resultado

✨ Recursos

• Pesquisar arquivos MindMup em todo o seu Google Drive (somente leitura)
• Navegação em árvore + exploração de seções para mapas mentais grandes — arquivos pequenos retornam conteúdo completo, arquivos grandes retornam um esboço que você pode explorar
• Isolamento de cache por cliente via cabeçalho X-Client-Id, para que diferentes usuários/ferramentas não compartilhem conteúdo em cache
• Modo de desenvolvimento com recarga automática via fastmcp run --reload + fonte montada por bind
• Servidor FastMCP com endpoints integrados /health e /ping
• Docker Compose para desenvolvimento e produção

🗺️ Fluxo de Ponta a Ponta

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

🔧 Ferramentas MCP Disponíveis

Fluxo de trabalho sugerido para agentes de IA: list_files → read_mindmap → se outline_only, ou search_mindmap (por palavra-chave) ou get_mindmap_section (por node_path de suggested_start_paths).

🚀 Começando

Pré-requisitos

• Python 3.12+
• Docker e docker-compose (necessários para make run-dev-docker / make run-prod) ; Ref. makefile
• Conta do Google Cloud Platform
• Um cliente MCP que suporte transporte HTTP (Claude Code ou Cursor)

Configuração da API do Google Drive

Etapa	Descrição	Imagem
1	Vá para Google Cloud Console e crie um novo projeto (o nível gratuito é suficiente — não é necessário faturamento para a API do Drive).
2	Ative a API do Google Drive.
3	Crie credenciais de Conta de Serviço: - "IAM & Admin" → "Service Accounts" → "Create Service Account" - Nenhuma função no nível do projeto é necessária (o compartilhamento do Drive lida com a autenticação) - Abra a SA → guia "Keys" → "Add Key" → JSON → baixe o arquivo de chave.
4	Codifique em Base64 todo o arquivo de chave JSON (veja Referência de Cabeçalho). ⚠️ Adicione o arquivo JSON ao .gitignore — nunca o envie para o repositório.
5	Compartilhe sua pasta do Google Drive com a SA: - Copie o valor de client_email do JSON - Clique com o botão direito na pasta → Compartilhar → cole o e-mail - Conceda acesso de Visualizador, desmarque "Notificar pessoas" - O compartilhamento se propaga para subpastas.

Nota sobre escopos: O servidor solicita auth/drive + auth/drive.file. Apesar do escopo amplo, com compartilhamento em nível de pasta Viewer, a SA só pode ler o que você compartilhou. Contas gerenciadas pelo workspace podem bloquear o compartilhamento externo — se isso ocorrer, peça ao seu administrador para permitir o compartilhamento de contas de serviço para o seu domínio.

Executar o Servidor

Docker (recomendado):

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

Python direto (sem Docker):

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

Verificar o Servidor

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

Se você não obtiver success, verifique docker logs <container> (modo Docker) ou stdout (modo Python).

Executar Testes

pip install -r requirements.txt
pytest

Configuração do Cliente MCP

Adicione à configuração do seu cliente MCP (~/.claude/mcp.json para Claude Code, ou suas configurações MCP do Cursor):

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

Referência de Cabeçalho

🩺 Solução de Problemas

🏗️ Estrutura do Projeto

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