# 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](https://console.cloud.google.com) → 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):**
```powershell
cd "C:\Users\<usuario>\Documents\MCP_Servers\googleDrive"
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```

**macOS / Linux:**
```bash
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:**
```powershell
.venv\Scripts\activate
python main.py
```

**macOS / Linux:**
```bash
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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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`:

```env
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:**
```powershell
Remove-Item ".\token.json"
python main.py
```

**macOS / Linux:**
```bash
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.