Google Drive MCP Server

Servidor MCP local em Python para ler/escrever Google Sheets, Slides e Drive a partir de sessões do Claude Code.

---

Como funciona

O servidor usa OAuth 2.0 Desktop App do GCP. No primeiro uso, abre o navegador para o fluxo de consentimento. Após aprovado, salva um token.json local. Nas execuções seguintes, reutiliza o token e o renova automaticamente quando expira — sem precisar abrir o navegador novamente.

Arquivos de autenticação:

Arquivo	O que é
credentials.json	Credenciais do app OAuth baixadas do GCP Console
token.json	Token de acesso gerado após o primeiro login (renovado automaticamente)

---

Configuração inicial (primeira vez)

1. Credenciais GCP

1. Acesse GCP Console → APIs & Services → Credentials
2. Crie um OAuth 2.0 Client ID (tipo: Desktop App)
3. Baixe o JSON e salve como credentials.json nesta pasta
4. Habilite as APIs no projeto GCP:
   • Google Sheets API
   • Google Slides API
   • Google Drive API

2. Instalar dependências

Windows (PowerShell):

cd "C:\Users\<usuario>\Documents\MCP_Servers\googleDrive"
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

macOS / Linux:

cd ~/Documents/MCP_Servers/googleDrive
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Primeiro login (OAuth)

Execute manualmente para abrir o navegador e autorizar:

Windows:

.venv\Scripts\activate
python main.py

macOS / Linux:

source .venv/bin/activate
python main.py

Após aprovar no navegador, token.json é criado e o servidor sobe. Pode encerrar com Ctrl+C — o token fica salvo para os próximos usos.

---

Registrar no Claude Code

Há duas formas de registrar o servidor MCP:

Opção A — Por projeto (.mcp.json)

Cria um arquivo .mcp.json na raiz do projeto. O MCP fica ativo apenas naquele projeto.

Windows:

{
  "mcpServers": {
    "google-drive": {
      "type": "stdio",
      "command": "C:\\Users\\<usuario>\\Documents\\MCP_Servers\\googleDrive\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\<usuario>\\Documents\\MCP_Servers\\googleDrive\\main.py"
      ]
    }
  }
}

macOS / Linux:

{
  "mcpServers": {
    "google-drive": {
      "type": "stdio",
      "command": "/Users/<usuario>/Documents/MCP_Servers/googleDrive/.venv/bin/python",
      "args": [
        "/Users/<usuario>/Documents/MCP_Servers/googleDrive/main.py"
      ]
    }
  }
}

Opção B — Global para o usuário (~/.claude/settings.json)

Adiciona o MCP nas configurações globais do Claude Code — fica disponível em todos os projetos.

Edite ~/.claude/settings.json (Windows: C:\Users\<usuario>\.claude\settings.json) e adicione a chave mcpServers:

Windows:

{
  "mcpServers": {
    "google-drive": {
      "type": "stdio",
      "command": "C:\\Users\\<usuario>\\Documents\\MCP_Servers\\googleDrive\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\<usuario>\\Documents\\MCP_Servers\\googleDrive\\main.py"
      ]
    }
  }
}

macOS / Linux:

{
  "mcpServers": {
    "google-drive": {
      "type": "stdio",
      "command": "/Users/<usuario>/Documents/MCP_Servers/googleDrive/.venv/bin/python",
      "args": [
        "/Users/<usuario>/Documents/MCP_Servers/googleDrive/main.py"
      ]
    }
  }
}

Use a Opção A quando o MCP é específico de um projeto. Use a Opção B quando quiser acesso em qualquer projeto.

---

Variáveis de ambiente (opcional)

Por padrão, o servidor procura credentials.json e token.json na própria pasta. Para mudar os caminhos, crie um .env baseado no .env.example:

GOOGLE_CREDENTIALS_PATH=credentials.json
GOOGLE_TOKEN_PATH=token.json

---

Ferramentas disponíveis (17 tools)

Google Sheets (7)

Tool	Descrição
sheets_read_range	Lê valores de um intervalo de células
sheets_write_range	Escreve valores em um intervalo
sheets_append_rows	Adiciona linhas ao final dos dados
sheets_batch_update_values	Escreve em múltiplos intervalos de uma vez
sheets_get_spreadsheet	Retorna metadados (título, abas)
sheets_create_spreadsheet	Cria nova planilha
sheets_add_sheet	Adiciona uma aba à planilha

Google Slides (7)

Tool	Descrição
slides_get_presentation	Retorna estrutura e títulos dos slides
slides_get_slide_content	Retorna textos e formas de um slide
slides_create_slide	Adiciona novo slide
slides_insert_text	Insere texto em uma forma
slides_replace_text	Localiza e substitui texto
slides_delete_slide	Remove um slide
slides_batch_update	Executa batch raw da API

Google Drive (3)

Tool	Descrição
drive_list_files	Lista/filtra arquivos (por tipo, query)
drive_search_files	Busca arquivos por nome
drive_get_file_metadata	Retorna metadados detalhados de um arquivo

Todos os tools aceitam ID direto ou URL completa do Google:

• 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
• https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms/edit

---

Troubleshooting

invalid_grant / token expirado sem auto-renovar

Delete o token.json e rode python main.py novamente para refazer o fluxo OAuth.

Windows:

Remove-Item ".\token.json"
python main.py

macOS / Linux:

rm token.json
python main.py

API não habilitada

Verifique se as três APIs estão ativas no GCP Console: Google Sheets API, Google Slides API, Google Drive API.

MCP não aparece no Claude Code

Verifique se o caminho do executável Python está correto:

• Windows: .venv\Scripts\python.exe
• macOS/Linux: .venv/bin/python

Use o caminho absoluto no .mcp.json ou settings.json — caminhos relativos não funcionam.