mcp-google-drive

Google Drive MCP

Inglês | Русский

A1 Google Drive MCP permite que um aplicativo de IA trabalhe com seu Google Drive em linguagem natural. Encontre um arquivo, organize pastas, envie e baixe conteúdo, exporte um Documento como Markdown, compartilhe com as pessoas certas — e mantenha a lixeira entre você e a exclusão permanente.

Ele usa a API do Google Drive com sua conta Google. Ele enxerga tanto o Meu Drive quanto drives compartilhados, trata "excluir" como a lixeira reversível e torna explícitos os limites da API do Drive, em vez de dar a entender que toda tarefa com arquivos é possível.

• 21 ferramentas. Pesquisa e metadados, pastas e movimentação, upload e download, exportação de Documentos/Planilhas/Apresentações, lixeira, compartilhamento e comentários.
• Conecta-se a partir da conversa. Diga "conectar Google Drive": o servidor guia você pelo cliente OAuth, captura o redirecionamento do Google em 127.0.0.1 com PKCE e mantém os tokens ele mesmo — sem arquivos de configuração, sem reiniciar.
• A lixeira vem primeiro. "Excluir" significa a lixeira reversível; a exclusão permanente é uma ferramenta deliberadamente separada que não pode ser acionada por acidente.
• Os documentos permanecem intactos. Documentos, Planilhas e Apresentações são movidos, copiados, exportados e convertidos como arquivos inteiros — o servidor nunca edita o texto dentro deles.
• Você escolhe o escopo. drive.readonly cobre todas as leituras e drive.file limita o acesso a arquivos criados pelo aplicativo; a superfície completa de ferramentas precisa de drive.

Comece com uma pergunta somente de leitura:

Encontre o documento do roteiro do projeto no meu Drive, exporte-o para Markdown e resuma-o.

Conectar o servidor · Explorar casos de uso · Abrir documentação técnica

Veja funcionando em um minuto

Você: Mostre o que há na pasta "Contratos 2025", do mais recente para o mais antigo.

Assistente: Lista os arquivos com seus tipos, proprietários e datas de modificação. Nada muda.

Você: Prepare uma subpasta "Arquivo" e mova tudo o que for mais antigo que um ano para ela.

Assistente: Mostra a pasta que criaria e os arquivos que moveria e, em seguida, pede confirmação.

Você: Confirmo.

Assistente: Cria a pasta e move os arquivos. Nada é compartilhado, enviado para a lixeira ou excluído, a menos que você peça separadamente.

Conteúdo

• Início rápido
• O que você pode pedir que ele faça
• Como seu Drive muda
• O que pode mudar
• Obtendo acesso
• Configuração
• Dados, limites e trabalho em segundo plano
• Documentação técnica
• Suporte

Início rápido

Você precisa do Node.js 20+ e de uma conta Google. As credenciais não são necessárias no momento da instalação — o servidor conecta-se a partir da conversa.

1. Adicione o servidor ao seu aplicativo de IA.
2. Diga "conectar Google Drive": o assistente guia você pela criação do cliente OAuth e aprovação do acesso sem editar arquivos de configuração.
3. Faça a pergunta somente de leitura acima.

codex mcp add google-drive \
  -- npx -y @a1-x-tech/mcp-google-drive@latest

codex mcp list

claude mcp add \
  --transport stdio --scope user google-drive \
  -- npx -y @a1-x-tech/mcp-google-drive@latest

claude mcp list

{
  "mcpServers": {
    "google-drive": {
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-drive@latest"]
    }
  }
}

{
  "mcpServers": {
    "google-drive": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-drive@latest"]
    }
  }
}

{
  "servers": {
    "google-drive": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-drive@latest"]
    }
  }
}

O que você pode pedir que ele faça

Encontrar e ler arquivos

• Encontre a planilha de orçamento do último trimestre e mostre onde ela está e quem é o proprietário.
• Exporte o resumo do projeto para Markdown e resuma as questões em aberto.
• Baixe o PDF do contrato assinado para minha pasta de relatórios.

Organizar e transferir conteúdo

• Crie uma pasta "Relatórios 2026" e mova os relatórios mensais para ela.
• Envie estas notas de reunião e converta-as em um Documento Google.
• Copie o modelo de proposta e renomeie a cópia para o novo cliente.

Compartilhar e discutir

• Compartilhe a pasta com um colega como comentarista e adicione uma nota ao convite.
• Liste os comentários em aberto no documento de design e resolva os que já foram tratados.
• Revogue o acesso do contratante externo ao arquivo.

Limpar deliberadamente

• Envie os rascunhos desatualizados para a lixeira — e restaure o que foi excluído por engano.
• Exclua permanentemente a pasta de uploads de teste depois que eu confirmar.
• Mostre o que está na lixeira antes de qualquer purga.

Como seu Drive muda

1. Tudo no Drive — incluindo pastas e itens de drives compartilhados — é um arquivo com um id. Os nomes não são únicos, então as ferramentas agem por ids, e nomes duplicados são permitidos: vale a pena pesquisar antes de criar.
2. "Excluir" significa a lixeira: reversível, purgada automaticamente pelo Google após cerca de 30 dias. A exclusão permanente ignora a lixeira, leva subárvores de pastas junto e vive em uma ferramenta deliberadamente separada.
3. Documentos, Planilhas e Apresentações Google são movidos, copiados, compartilhados, exportados e convertidos como unidades inteiras. O servidor não tem ferramenta que edite texto dentro de um Documento ou células dentro de uma Planilha.
4. Uma gravação nunca é repetida após uma falha incerta: novas tentativas após erros de rede e 5xx aplicam-se apenas a leituras, então uma cópia, upload ou nova pasta não pode ser duplicada pelas suas costas.

Uploads integrados são limitados a 5 MB (arquivos maiores passam por uma sessão retomável via raw_request), exportações a 10 MB conforme a API do Drive. Comentários criados pela API não podem ser ancorados a uma passagem específica dentro de um Documento.

O que pode mudar

O cliente de IA controla os avisos de confirmação. O servidor marca ferramentas de leitura, gravação e destrutivas para que o cliente possa distinguir uma inspeção de uma alteração ao vivo.

Obtendo acesso

O Google Drive exige OAuth 2.0; uma chave de API não é suficiente. Há duas formas de entrar, e a primeira não precisa de arquivos de configuração.

Conectar pelo chat (recomendado)

Diga "conectar Google Drive" e o assistente executa o fluxo com você:

1. setup_instructions imprime a lista de verificação: criar ou selecionar um projeto do Google Cloud, ativar a API Google Drive, configurar a tela de consentimento e criar um cliente OAuth de aplicativo de desktop.
2. Baixe o JSON desse cliente ("Baixar JSON") e dê ao assistente o caminho dele — set_client o armazena somente para o proprietário. O segredo nunca passa pela conversa.
3. start_login retorna um link de consentimento do Google. Abra-o nesta máquina e aprove; o código volta para um ouvinte de uso único em 127.0.0.1 (PKCE), nunca pelo chat.
4. finish_login troca o código e salva os tokens em ~/.config/mcp-google-drive/credentials.json (modo 0600) e os verifica com uma chamada real à API do Google Drive — então uma API ainda desativada é detectada ali mesmo.

Os tokens são relidos a cada chamada, então a conexão funciona imediatamente — sem reiniciar o aplicativo de IA. auth_status mostra o que está conectado, logout revoga e exclui.

Variáveis de ambiente (CI, instalações não assistidas)

1. Crie ou selecione um projeto do Google Cloud e ative a API Google Drive.

2. Configure a tela de consentimento OAuth e crie um cliente OAuth de aplicativo de desktop.

3. Autorize a conta Google cujos arquivos o servidor deve trabalhar. O Playground OAuth 2.0 pode obter o token de atualização quando Usar suas próprias credenciais OAuth estiver ativado.

4. Solicite o escopo mais restrito que cubra seu uso:

   Escopo	Habilita
   https://www.googleapis.com/auth/drive.readonly	As ferramentas somente de leitura: pesquisa, metadados, download, exportação e listagem de drives compartilhados.
   https://www.googleapis.com/auth/drive.file	Apenas arquivos criados ou abertos por este aplicativo — suficiente para fluxos de upload e organização em arquivos de propriedade do aplicativo.
   https://www.googleapis.com/auth/drive	A superfície completa de ferramentas: compartilhamento, lixeira, exclusão e comentários em arquivos arbitrários.

O servidor usa o escopo com o qual o token de atualização foi emitido; uma chamada fora dele falha com um erro insufficientPermissions.

Tokens de atualização OAuth em modo de teste podem expirar após sete dias. Publique o aplicativo OAuth ou use um aplicativo Interno em um domínio do Workspace quando precisar de acesso de longa duração. Trate o segredo do cliente e o token de atualização como senhas.

Configuração

Toda variável é opcional — sem nenhuma delas, o servidor conecta-se pelo chat.

* Forneça o trio OAuth ou um token de acesso.

Sem nenhuma credencial, o servidor ainda inicia e completa o handshake MCP; a primeira chamada de ferramenta responde com as variáveis exatas a definir, em vez de um servidor morto.

Dados, limites e trabalho em segundo plano

• As solicitações vão para o Google Drive. O servidor local atualiza os tokens OAuth do Google e chama a API do Drive. Sua telemetria anônima contém um ID de instalação, versão do pacote, cliente de IA e versões de plataforma, e nomes de ferramentas — nunca tokens OAuth, conteúdo de arquivos, argumentos de ferramentas ou prompts. Defina ASKADS_TELEMETRY=0 para optar por não participar.
• O Google aplica cotas e limites de tamanho. Uploads pela ferramenta integrada são limitados a 5 MB e exportações a 10 MB. Em 429, o servidor usa backoff; leituras também tentam novamente após erros de rede e 5xx, enquanto gravações não são repetidas após uma falha incerta.
• Arquivos locais são tratados com cautela. Downloads salvam apenas em caminhos absolutos e recusam sobrescrever um arquivo existente, a menos que solicitado; retornos inline limitam-se a 100 KB de conteúdo textual.
• Não há polling em segundo plano. O servidor roda apenas quando chamado; nada monitora seu Drive entre solicitações. Se seu aplicativo de IA suportar tarefas agendadas, ele pode verificar mudanças periodicamente.

Documentação técnica

• Catálogo de capacidades MCP — páginas orientadas a tarefas para cada ferramenta.
• Todas as ferramentas e entradas
• Documentação de desenvolvimento
• Documentação de publicação
• Referência da API do Google Drive

Suporte

Encontrou um bug ou precisa de um cenário? Crie um issue ou escreva no Telegram.

Você chegou ao fim!