Gdrive Cloudflare worker

Servidor MCP remoto para Google Drive e Sheets executado em Cloudflare Workers com suporte completo a OAuth 2.0.

Documentação

mcp-gdrive-cf

Servidor MCP remoto para Google Drive e Sheets executando em Cloudflare Workers com suporte completo a OAuth 2.0.

Pronto para Produção ✅ | 11 Ferramentas | OAuth 2.0 | PKCE | Rede Global de Edge

Adaptado de isaacphi/mcp-gdrive para executar como um servidor MCP remoto HTTP/SSE na rede de edge da Cloudflare com capacidades completas de servidor de autorização OAuth 2.0.

🚀 Início Rápido

\`bash

1. Clone e instale

git clone https://github.com/brianmoney/mcp-gdrive-cf.git cd mcp-gdrive-cf npm install

2. Crie namespaces KV

wrangler kv:namespace create KV_TOKENS wrangler kv:namespace create KV_CLIENTS

3. Atualize o wrangler.toml com seus IDs de namespace

4. Configure as credenciais OAuth do Google

wrangler secret put GOOGLE_CLIENT_SECRET

5. Implante

wrangler deploy

6. Teste com o MCP Inspector

npx @modelcontextprotocol/inspector https://your-worker.workers.dev/sse \`

✨ Recursos

Operações do Drive

🔍 Pesquisa - Pesquisa básica e avançada com filtros (tipo MIME, proprietário, datas, drives compartilhados)
📄 Leitura - Leia qualquer arquivo com mais de 22 formatos de exportação (PDF, DOCX, XLSX, Markdown, etc.)
📁 Criar Pastas - Organize arquivos com estruturas de pastas aninhadas
⬆️ Upload - Envie arquivos de até 5MB
🗑️ Excluir - Mova arquivos para a lixeira
📦 Mover - Reorganize arquivos entre pastas
🔐 Compartilhar - Adicione permissões (leitor, editor, comentarista, proprietário)

Operações do Sheets

📊 Leitura - Leitura em lote de múltiplos intervalos
✏️ Atualizar - Atualize células individuais
➕ Adicionar - Adicione linhas a planilhas

Infraestrutura

☁️ Rede Global de Edge - Executa em Cloudflare Workers em todo o mundo
🔐 Servidor OAuth 2.0 - Servidor de autorização completo com suporte a PKCE
🔑 Registro Dinâmico de Clientes - Onboarding automático de clientes
🔄 Atualização Automática de Token - Renovação contínua de tokens do Google
📡 Transporte SSE - Server-Sent Events em tempo real
🛡️ Seguro - Apenas HTTPS, armazenamento de tokens criptografado

🎯 O Que Torna Isso Diferente

Diferente do mcp-gdrive\ original baseado em STDIO, esta implementação:

Executa remotamente em Cloudflare Workers (sem processo local)
Servidor de autorização OAuth 2.0 completo (não apenas cliente OAuth)
Suporte a múltiplos clientes via registro dinâmico de clientes
Segurança PKCE para clientes públicos
Mais de 22 formatos de exportação para arquivos do Drive
Operações de escrita (criar, excluir, mover, compartilhar, enviar)
Testado em produção com cargas de trabalho reais

📋 Pré-requisitos

Necessário

Conta Cloudflare com Workers habilitados (o plano gratuito funciona)
Projeto Google Cloud com Drive API e Sheets API habilitadas
Node.js LTS (v18+)
Wrangler CLI (npm install -g wrangler\)

Configuração do Google Cloud

Crie um projeto no Google Cloud Console
Habilite as APIs:
- Google Drive API
- Google Sheets API
Crie credenciais OAuth 2.0:
- Tipo: Aplicação web
- Redirect URIs: https://your-worker.workers.dev/google/callback\
Escopos OAuth necessários:
- https://www.googleapis.com/auth/drive\
- https://www.googleapis.com/auth/spreadsheets\

🔧 Instalação e Implantação

1. Instalar Dependências

\`bash npm install \`

2. Criar Namespaces KV

\`bash

Para tokens de sessão de usuário

wrangler kv:namespace create KV_TOKENS

Para registros de clientes OAuth

wrangler kv:namespace create KV_CLIENTS \`

Copie os IDs dos namespaces para wrangler.toml\:

\`toml [[kv_namespaces]] binding = "KV_TOKENS" id = "your-tokens-namespace-id"

[[kv_namespaces]] binding = "KV_CLIENTS" id = "your-clients-namespace-id" \`

3. Configurar Variáveis de Ambiente

Adicione em wrangler.toml\:

\`toml [vars] GOOGLE_CLIENT_ID = "your-client-id.apps.googleusercontent.com" \`

Defina os segredos:

\`bash

Segredo do cliente OAuth do Google

wrangler secret put GOOGLE_CLIENT_SECRET \`

4. Implantar

\`bash wrangler deploy \`

Seu worker estará disponível em: https://your-worker-name.your-account.workers.dev\

🔐 Fluxo OAuth 2.0

Este servidor implementa um servidor de autorização OAuth 2.0 completo de acordo com a especificação MCP.

Usando o MCP Inspector

A maneira mais fácil de testar o fluxo OAuth:

\`bash npx @modelcontextprotocol/inspector https://your-worker.workers.dev/sse \`

Descoberta - O Inspector descobre automaticamente os endpoints OAuth
Registro - Clique em "Guided Setup" → registra o cliente automaticamente
Autorização - Redireciona para o Google → autentica → redireciona de volta
Troca de Token - Troca automaticamente o código pelo token de acesso
Usar Ferramentas - Todas as 11 ferramentas agora disponíveis!

Recursos de Segurança

✅ PKCE (RFC 7636) - Chave de Prova para Troca de Código
✅ Parâmetro de Estado - Proteção CSRF
✅ Apenas HTTPS - Aplicado por Cloudflare Workers
✅ Armazenamento Seguro de Tokens - Criptografado em Workers KV
✅ Expiração de Token - Tokens de acesso expiram em 1 hora
✅ Hash de Segredo do Cliente - Armazenamento com hash SHA-256
✅ Código de Autorização de Uso Único - Códigos excluídos após a troca

🛠️ Ferramentas Disponíveis

Ferramentas do Drive

gdrive_search\ - Pesquisa básica em todos os arquivos
gdrive_search_advanced\ - Pesquisa avançada com filtros
gdrive_read_file\ - Leia arquivos com mais de 22 formatos de exportação
gdrive_create_folder\ - Crie pastas
gdrive_upload_file\ - Envie arquivos (até 5MB)
gdrive_delete_file\ - Mova arquivos para a lixeira
gdrive_move_file\ - Mova arquivos entre pastas
gdrive_add_permission\ - Compartilhe arquivos/pastas

Ferramentas do Sheets

gsheets_read\ - Leia múltiplos intervalos
gsheets_update_cell\ - Atualize células individuais
gsheets_append_row\ - Adicione linhas

🔌 Configuração do Cliente

VS Code com Extensão MCP

Crie .vscode/settings.json\:

\`json { "mcp.servers": { "gdrive": { "url": "https://your-worker.workers.dev/sse", "authorization": { "type": "oauth2" } } } } \`

Claude Desktop / Cline

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json\
Windows: %APPDATA%\\Claude\\claude_desktop_config.json\

\`json { "mcpServers": { "gdrive": { "url": "https://your-worker.workers.dev/sse" } } } \`

🧪 Testes

Desenvolvimento Local

\`bash npm start

Servidor disponível em http://localhost:8788

\`

Testar com MCP Inspector

\`bash npx @modelcontextprotocol/inspector http://localhost:8788/sse \`

Verificar Logs do CloudFlare

\`bash wrangler tail --format pretty \`

🐛 Solução de Problemas

"Falha ao descobrir metadados OAuth"

Solução:

Garanta que /.well-known/oauth-authorization-server\ retorne JSON válido
Verifique se os cabeçalhos CORS estão presentes
Verifique se a versão mais recente está implantada: wrangler deploy\

"Falha na troca de token: HTTP 400"

Soluções:

Verifique se o code_verifier corresponde ao code_challenge original
Garanta que o redirect_uri corresponda exatamente ao registro
Verifique se as credenciais do cliente estão corretas
Verifique os logs do CloudFlare: wrangler tail\

Ferramentas não funcionando

Soluções:

Verifique se os escopos OAuth do Google incluem drive\ e spreadsheets\
Reautentique se os escopos mudaram: visite /google/authorize\
Verifique se o Worker tem um token de acesso Google válido
Verifique os bindings de namespace KV em wrangler.toml\

📊 Desempenho e Limites

Recurso	Limite	Observações
Tempo Limite de Requisição	30 segundos	Limite do CloudFlare Workers
Upload de Arquivo	5 MB	Limite da API de upload simples
Exportação de Arquivo	10 MB	Limite de exportação do Google Drive
Armazenamento de Token	30 dias	Limpeza automática
Código de Autorização	10 minutos	Uso único
Token de Acesso	1 hora	Atualizado automaticamente

🔒 Melhores Práticas de Segurança

Nunca faça commit de segredos - Use wrangler secret put\
Rotacione segredos de clientes - Regere periodicamente as credenciais OAuth
Monitore o acesso - Use o CloudFlare Analytics para rastrear o uso
Limite os escopos OAuth - Solicite apenas as permissões Google necessárias
Use PKCE - Sempre use PKCE para clientes públicos
Valide URIs de redirecionamento - Coloque na lista de permissões URIs exatas no Google Console
Habilite 2FA - Proteja suas contas CloudFlare e Google

📄 Licença

Licença MIT

🙏 Agradecimentos

isaacphi/mcp-gdrive - Implementação STDIO original
Model Context Protocol - Especificação MCP
CloudFlare Workers - Plataforma serverless

Feito com ☁️ por Brian Money