Google Docs & Drive

Interaja com Google Docs e Google Drive para criação, edição de documentos e gerenciamento de arquivos, com suporte para unidades compartilhadas.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP Ultimate para Google Docs & Drive

Conecte o Claude Desktop (ou outros clientes MCP) aos seus Google Docs e Google Drive!

🔥 Confira 15 tarefas poderosas que você pode realizar com este servidor aprimorado! 📁 NOVO: Capacidades completas de gerenciamento de arquivos do Google Drive!

Este servidor abrangente utiliza o Model Context Protocol (MCP) e a biblioteca fastmcp para fornecer ferramentas de leitura, escrita, formatação, estruturação de Documentos Google e gerenciamento de todo o seu Google Drive. Ele atua como uma ponte poderosa, permitindo que assistentes de IA como o Claude interajam com seus documentos e arquivos programaticamente com capacidades avançadas.

Recursos:

Acesso e Edição de Documentos

Ler Documentos: Leia conteúdo com readGoogleDoc (texto simples, estrutura JSON ou markdown)
Adicionar a Documentos: Adicione texto a documentos com appendToGoogleDoc
Inserir Texto: Coloque texto em posições específicas com insertText
Excluir Conteúdo: Remova conteúdo de um documento com deleteRange

Formatação e Estilo

Formatação de Texto: Aplique estilos avançados com applyTextStyle (negrito, itálico, cores, etc.)
Formatação de Parágrafos: Controle o layout de parágrafos com applyParagraphStyle (alinhamento, espaçamento, etc.)
Localizar e Formatar: Formate por conteúdo de texto usando formatMatchingText (suporte legado)

Estrutura de Documentos

Tabelas: Crie tabelas com insertTable
Quebras de Página: Insira quebras de página com insertPageBreak
Recursos Experimentais: Ferramentas como fixListFormatting para detecção automática de listas

🆕 Gerenciamento de Arquivos do Google Drive

Descoberta de Documentos: Encontre e liste documentos com listGoogleDocs, searchGoogleDocs, getRecentGoogleDocs
Informações de Documentos: Obtenha metadados detalhados com getDocumentInfo
Gerenciamento de Pastas: Crie pastas (createFolder), liste conteúdos (listFolderContents), obtenha informações (getFolderInfo)
Operações com Arquivos: Mova (moveFile), copie (copyFile), renomeie (renameFile), exclua (deleteFile)
Criação de Documentos: Crie novos documentos (createDocument) ou a partir de modelos (createFromTemplate)
🚀 Suporte a Unidades Compartilhadas: Suporte completo para unidades compartilhadas do Google Workspace! Todas as operações agora funcionam perfeitamente com unidades compartilhadas

Integração

Autenticação Google: Autenticação OAuth 2.0 segura com acesso completo ao Drive
Compatível com MCP: Projetado para uso com Claude e outros clientes MCP
Integração com VS Code: Guia de configuração para a extensão MCP do VS Code

Pré-requisitos

Antes de começar, certifique-se de ter:

Node.js e npm: Uma versão recente do Node.js (que inclui npm) instalada no seu computador. Você pode baixá-la em nodejs.org. (Versão 18 ou superior recomendada).
Git: Necessário para clonar este repositório. (Baixar Git).
Uma Conta Google: A conta que possui ou tem acesso aos Google Docs com os quais você deseja interagir.
Familiaridade com Linha de Comando: Conforto básico usando um terminal ou prompt de comando (como Terminal no macOS/Linux, ou Prompt de Comando/PowerShell no Windows).
Claude Desktop (Opcional): Se seu objetivo é conectar este servidor ao Claude, você precisará do aplicativo Claude Desktop instalado.

Instruções de Configuração

Siga estes passos cuidadosamente para colocar sua própria instância do servidor em funcionamento.

Passo 1: Projeto e Credenciais no Google Cloud (A Parte Importante!)

Este servidor precisa de permissão para falar com as APIs do Google em seu nome. Você criará "chaves" especiais (credenciais) que somente seu servidor usará.

Acesse o Google Cloud Console: Abra seu navegador e vá para o Google Cloud Console. Talvez seja necessário fazer login com sua Conta Google.
Crie ou Selecione um Projeto:
- Se você não tiver um projeto, clique no menu suspenso de projetos próximo ao topo e selecione "NOVO PROJETO". Dê um nome (ex.: "Meu Servidor MCP Docs") e clique em "CRIAR".
  - Se você tiver projetos existentes, pode selecionar um ou criar um novo.
Ative as APIs: Você precisa ativar os serviços Google específicos que este servidor utiliza.
- Na barra de pesquisa no topo, digite "APIs e Serviços" e selecione "Biblioteca".
  - Pesquise por " API Google Docs " e clique nela. Em seguida, clique no botão " ATIVAR ".
  - Pesquise por " API Google Drive " e clique nela. Em seguida, clique no botão " ATIVAR " (isso geralmente é necessário para encontrar arquivos ou permissões).
Configure a Tela de Consentimento OAuth: Esta tela informa aos usuários (geralmente apenas você) quais permissões seu aplicativo solicita.
- No menu à esquerda, clique em "APIs e Serviços" -> " Tela de consentimento OAuth ".
  - Escolha o Tipo de Usuário: Selecione " Externo " e clique em "CRIAR".
  - Preencha as Informações do Aplicativo:
  - Nome do aplicativo: Dê um nome que os usuários verão (ex.: "Acesso MCP Docs do Claude"). - E-mail de suporte do usuário: Selecione seu endereço de e-mail. - Informações de contato do desenvolvedor: Insira seu endereço de e-mail.
  - Clique em " SALVAR E CONTINUAR ".
  - Escopos: Clique em " ADICIONAR OU REMOVER ESCOPOS ". Pesquise e adicione os seguintes escopos:
  - https://www.googleapis.com/auth/documents (Permite ler/gravar documentos) - https://www.googleapis.com/auth/drive.file (Permite acesso a arquivos específicos abertos/criados pelo aplicativo) - Clique em " ATUALIZAR ".
  - Clique em " SALVAR E CONTINUAR ".
  - Usuários de Teste: Clique em " ADICIONAR USUÁRIOS ". Insira o mesmo endereço de e-mail Google com o qual você está logado. Clique em " ADICIONAR ". Isso permite que você use o aplicativo enquanto ele está em modo de "teste".
  - Clique em " SALVAR E CONTINUAR ". Revise o resumo e clique em " VOLTAR AO PAINEL ".
Crie Credenciais (As Chaves!):
- No menu à esquerda, clique em "APIs e Serviços" -> " Credenciais ".
  - Clique em " + CRIAR CREDENCIAIS " no topo e escolha " ID do cliente OAuth ".
  - Tipo de aplicativo: Selecione " Aplicativo de desktop " no menu suspenso.
  - Nome: Dê um nome (ex.: "Cliente Desktop MCP Docs").
  - Clique em " CRIAR ".
⬇️ BAIXE O ARQUIVO DE CREDENCIAIS: Uma caixa aparecerá mostrando seu ID de Cliente. Clique no botão " BAIXAR JSON ".
- Salve este arquivo. Ele provavelmente terá um nome como client_secret_....json.
  - IMPORTANTE: Renomeie o arquivo baixado exatamente para credentials.json.
⚠️ AVISO DE SEGURANÇA: Trate este arquivo credentials.json como uma senha! Não o compartilhe publicamente e nunca o envie para o GitHub. Qualquer pessoa com este arquivo poderia potencialmente se passar pelo seu aplicativo (embora ainda precisasse do consentimento do usuário para acessar dados).

Passo 2: Obtenha o Código do Servidor

Clone o Repositório: Abra seu terminal/prompt de comando e execute:

git clone https://github.com/jasonWong-serviceDirect/google-docs-mcp-shared.git mcp-googledocs-server

Navegue para o Diretório:
```
cd mcp-googledocs-server
```
Coloque as Credenciais: Mova ou copie o arquivo credentials.json que você baixou e renomeou (do Passo 1.6) diretamente para esta pasta mcp-googledocs-server.

Passo 3: Instale as Dependências

Seu servidor precisa de algumas bibliotecas auxiliares especificadas no arquivo package.json.

No seu terminal (certifique-se de estar dentro do diretório mcp-googledocs-server), execute:
```
npm install
```
Isso baixará e instalará todos os pacotes necessários em uma pasta node_modules.

Passo 4: Compile o Código do Servidor

O servidor é escrito em TypeScript (.ts), mas precisamos compilá-lo em JavaScript (.js) que o Node.js possa executar diretamente.

No seu terminal, execute:
```
npm run build
```
Isso usa o compilador TypeScript (tsc) para criar uma pasta dist contendo os arquivos JavaScript compilados.

Passo 5: Primeira Execução e Autorização Google (Somente Uma Vez)

Agora você precisa executar o servidor manualmente uma vez para conceder permissão de acesso aos dados da sua conta Google. Isso criará um arquivo token.json que salva sua concessão de permissão.

No seu terminal, execute o servidor compilado usando node:
```
node ./dist/server.js
```
Observe o Terminal: O script imprimirá:
- Mensagens de status (como "Tentando autorizar...").
  - Uma mensagem "Autorize este aplicativo visitando esta url:" seguida por uma URL longa https://accounts.google.com/....
Autorize no Navegador:
- Copie a URL longa inteira do terminal.
  - Cole a URL no seu navegador e pressione Enter.
  - Faça login com a mesma conta Google que você adicionou como Usuário de Teste no Passo 1.4.
  - O Google mostrará uma tela pedindo permissão para seu aplicativo ("Acesso MCP Docs do Claude" ou similar) acessar Google Docs/Drive. Revise e clique em " Permitir " ou " Conceder ".
Obtenha o Código de Autorização:
- Após clicar em Permitir, seu navegador provavelmente tentará redirecionar para http://localhost e mostrará um erro "Este site não pode ser acessado". ISSO É NORMAL!
  - Observe atentamente a URL na barra de endereços do seu navegador. Ela se parecerá com http://localhost/?code=4/0Axxxxxxxxxxxxxx&scope=...
  - Copie a longa sequência de caracteres entre code= e a parte &scope. Este é seu código de autorização de uso único.
Cole o Código no Terminal: Volte ao terminal onde o script está aguardando ("Insira o código desta página aqui:"). Cole o código que você acabou de copiar.
Pressione Enter.
Sucesso! O script deverá imprimir:
- "Autenticação bem-sucedida!"
  - "Token armazenado em.../token.json"
  - Em seguida, terminará de iniciar e provavelmente imprimirá "Aguardando conexão do cliente MCP via stdio..." ou similar, e então sairá (ou você pode pressionar Ctrl+C para interrompê-lo).
✅ Verifique: Você agora deve ver um novo arquivo chamado token.json na sua pasta mcp-googledocs-server.
⚠️ AVISO DE SEGURANÇA: Este arquivo token.json contém a chave que permite ao servidor acessar sua conta Google sem perguntar novamente. Proteja-o como uma senha. Não o envie para o GitHub. O arquivo .gitignore incluído deve evitar isso automaticamente.

Passo 6: Configure o Claude Desktop (Opcional)

Se você quiser usar este servidor com o Claude Desktop, precisa informar ao Claude como executá-lo.

Encontre Seu Caminho Absoluto: Você precisa do caminho completo para o código do servidor.
- No seu terminal, certifique-se de ainda estar dentro do diretório mcp-googledocs-server.
  - Execute o comando pwd (no macOS/Linux) ou cd (no Windows, apenas exibe o caminho).
  - Copie o caminho completo (ex.: /Users/yourname/projects/mcp-googledocs-server ou C:\Users\yourname\projects\mcp-googledocs-server).
Localize mcp_config.json: Encontre o arquivo de configuração do Claude:
- macOS: ~/Library/Application Support/Claude/mcp_config.json (Talvez seja necessário usar o menu "Ir" do Finder -> "Ir para a Pasta..." e colar ~/Library/Application Support/Claude/)
  - Windows: %APPDATA%\Claude\mcp_config.json (Cole %APPDATA%\Claude na barra de endereços do Explorador de Arquivos)
  - Linux: ~/.config/Claude/mcp_config.json
  - Se a pasta Claude ou o arquivo mcp_config.json não existirem, crie-os.
Edite mcp_config.json: Abra o arquivo em um editor de texto. Adicione ou modifique a seção mcpServers assim, substituindo /PATH/TO/YOUR/CLONED/REPO pelo caminho absoluto real que você copiou no Passo 6.1:
```
{
  "mcpServers": {
    "google-docs-mcp": {
      "command": "node",
      "args": [
        "/PATH/TO/YOUR/CLONED/REPO/mcp-googledocs-server/dist/server.js"
      ],
      "env": {}
    }
    // Add commas here if you have other servers defined
  }
  // Other Claude settings might be here
}
```
- Certifique-se de que o caminho em "args" está correto e é absoluto!
  - Se o arquivo já existia, mescle cuidadosamente esta entrada no objeto mcpServers existente. Garanta que o JSON seja válido (verifique as vírgulas!).
Salve mcp_config.json.
Reinicie o Claude Desktop: Feche o Claude completamente e reabra-o.

Uso com o Claude Desktop

Após a configuração, você poderá usar as ferramentas em suas conversas com o Claude:

"Use o servidor google-docs-mcp para ler o documento com ID YOUR_GOOGLE_DOC_ID."
"Você pode obter o conteúdo do Google Doc YOUR_GOOGLE_DOC_ID?"
"Adicione 'Isto foi adicionado pelo Claude!' ao documento YOUR_GOOGLE_DOC_ID usando a ferramenta google-docs-mcp."

Exemplos de Uso Avançado:

Estilo de Texto: "Use applyTextStyle para deixar o texto 'Important Section' em negrito e vermelho (#FF0000) no documento YOUR_GOOGLE_DOC_ID."
Estilo de Parágrafo: "Use applyParagraphStyle para centralizar o parágrafo que contém 'Title Here' no documento YOUR_GOOGLE_DOC_ID."
Criação de Tabela: "Insira uma tabela 3x4 no índice 500 do documento YOUR_GOOGLE_DOC_ID usando a ferramenta insertTable."
Formatação Legada: "Use formatMatchingText para encontrar a segunda ocorrência de 'Project Alpha' e deixá-la azul (#0000FF) no documento YOUR_GOOGLE_DOC_ID."

🚀 Suporte a Shared Drives:

O servidor agora oferece suporte total aos shared drives do Google Workspace! Você pode:

Listar conteúdos de shared drives: "Liste todos os documentos no shared drive SHARED_DRIVE_ID usando listGoogleDocs com corpora='drive'"
Pesquisar em todos os drives: "Pesquise por 'budget' em todos os meus drives usando searchGoogleDocs com corpora='allDrives'"
Criar em shared drives: "Crie um novo documento no shared drive SHARED_DRIVE_ID usando createDocument com o parâmetro driveId"
Listar pasta em shared drive: "Liste o conteúdo da pasta FOLDER_ID no shared drive DRIVE_ID usando listFolderContents"

O parâmetro corpora controla o escopo da pesquisa:

'user' (padrão): Apenas o drive pessoal do usuário
'drive': Um shared drive específico (requer driveId)
'allDrives': Todos os drives acessíveis, incluindo shared drives

Lembre-se de substituir YOUR_GOOGLE_DOC_ID pelo ID real da URL de um Google Doc (a string longa entre /d/ e /edit).

O Claude iniciará automaticamente o seu servidor em segundo plano quando necessário, usando o comando que você forneceu. Você não precisa executar node ./dist/server.js manualmente mais.

Segurança e Armazenamento de Tokens

.gitignore: Este repositório inclui um arquivo .gitignore que deve impedir que você envie acidentalmente seus arquivos sensíveis credentials.json e token.json. Não remova essas linhas de .gitignore.
Armazenamento de Tokens: Este servidor armazena o token de autorização do Google (token.json) diretamente na pasta do projeto para simplificar a configuração. Em ambientes de produção ou mais sensíveis à segurança, considere armazenar esse token de forma mais segura, como usando chaves do sistema, arquivos criptografados ou serviços dedicados de gerenciamento de segredos.

Solução de Problemas

O Claude mostra "Failed" ou "Could not attach":
- Verifique novamente o caminho absoluto em mcp_config.json.
  - Certifique-se de que você executou npm run build com sucesso e que a pasta dist existe.
  - Tente executar o comando de mcp_config.json manualmente no seu terminal: node /PATH/TO/YOUR/CLONED/REPO/mcp-googledocs-server/dist/server.js. Procure por erros exibidos.
  - Verifique os logs do Claude Desktop (consulte o guia oficial de depuração do MCP).
  - Certifique-se de que todas as mensagens de status console.log no código do servidor foram alteradas para console.error.
Erros de Autorização do Google:
- Certifique-se de que você habilitou as APIs corretas (Docs, Drive).
  - Certifique-se de que você adicionou seu e-mail como Usuário de Teste na Tela de Consentimento OAuth.
  - Verifique se o arquivo credentials.json está corretamente colocado na raiz do projeto.

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes. (Nota: Você deve adicionar um arquivo LICENSE contendo o texto da Licença MIT ao seu repositório).