mcp-google-forms

Google Forms MCP

English | Русский

A1 Google Forms MCP permite que um aplicativo de IA crie e gerencie Google Forms em linguagem natural. Crie uma pesquisa, escolha suas perguntas, publique quando estiver pronto, leia as respostas e use notificações para novos envios.

Ele usa a API do Google Forms com sua conta Google. Ele distingue um formulário de rascunho de um formulário publicado e torna explícitos os limites da API do Forms, em vez de dar a entender que toda tarefa de formulário é possível.

• 19 ferramentas. Inspecione a estrutura do formulário e as respostas, crie e edite formulários e perguntas, gerencie a publicação e configure monitoramentos do Pub/Sub.
• Conecta-se pela conversa. Diga "conectar Google Forms": o servidor orienta 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.
• Publique deliberadamente. Formulários criados pela API começam não publicados, então não podem coletar respostas até que você os publique.
• As respostas permanecem intactas. A API pode ler respostas, mas não pode criá-las ou editá-las; o servidor não tem ferramenta que envie respostas.
• Escopos mínimos do Google. Ele usa forms.body e forms.responses.readonly, sem acesso amplo ao Drive.

Comece com uma pergunta somente leitura:

Mostre-me as respostas de ontem do formulário de feedback do cliente e resuma as respostas de texto livre.

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

Veja funcionando em um minuto

Você: Mostre-me as perguntas e as configurações de resposta do formulário de feedback do cliente.

Assistente: Mostra o formulário, seus itens, se está publicado e se aceita respostas. Nada muda.

Você: Prepare uma pergunta obrigatória de avaliação de 1 a 5 chamada "Como foi sua experiência?" após a primeira pergunta.

Assistente: Mostra o formulário de destino, a posição e a pergunta proposta e pede confirmação antes de adicioná-la.

Você: Confirmo.

Assistente: Adiciona a pergunta ao formulário. Ele não publica nem fecha o formulário, a menos que você peça separadamente.

Conteúdo

• Início rápido
• O que você pode pedir para ele fazer
• Como um formulário 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 de Node.js 20+ e uma conta Google. As credenciais não são necessárias na instalação — o servidor se conecta pela conversa.

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

codex mcp add google-forms \
  -- npx -y mcp-google-forms@latest

codex mcp list

claude mcp add \
  --transport stdio --scope user google-forms \
  -- npx -y mcp-google-forms@latest

claude mcp list

{
  "mcpServers": {
    "google-forms": {
      "command": "npx",
      "args": ["-y", "mcp-google-forms@latest"]
    }
  }
}

{
  "mcpServers": {
    "google-forms": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-forms@latest"]
    }
  }
}

{
  "servers": {
    "google-forms": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-forms@latest"]
    }
  }
}

O que você pode pedir para ele fazer

Inspecionar uma pesquisa e suas respostas

• Mostre as perguntas deste formulário, as configurações de resposta e o link do respondente.
• Quantas respostas chegaram desde segunda-feira? Resuma o feedback de texto livre.
• Mostre uma resposta por ID.

Criar e melhorar um formulário

• Crie um formulário de RSVP com nome, preferência de refeição e data de chegada.
• Adicione uma pergunta obrigatória de avaliação, lista suspensa, data, hora, escolha ou texto.
• Reordene uma pergunta ou atualize um título, descrição, modo de questionário ou coleta de e-mail.

Publicar e conectar notificações

• Publique um formulário preparado e mostre a URL do respondente.
• Pare de aceitar novas respostas sem excluir o formulário.
• Crie, renove ou remova um monitoramento do Cloud Pub/Sub para novos envios.

Como um formulário muda

1. create_form cria um formulário, que começa não publicado por padrão.
2. As perguntas são itens, identificados pela posição no formulário.
3. Publicar torna um formulário disponível para os respondentes; fechar a coleta de respostas o mantém publicado, mas interrompe novos envios.
4. As respostas são um registro separado somente leitura. A API não pode enviar, editar ou excluir a resposta de um respondente.

Perguntas com upload de arquivo não podem ser criadas pela API do Forms, embora itens existentes de upload de arquivo possam ser lidos. Formulários legados criados antes do modelo de publicação do Google podem não suportar configurações de publicação.

O que pode mudar

O cliente de IA controla os avisos de confirmação. O servidor marca leituras, gravações e ferramentas destrutivas para que o cliente possa distinguir uma inspeção de uma mudança ao vivo.

Obtendo acesso

O Google Forms 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 Forms" e o assistente executa o fluxo com você:

1. setup_instructions imprime a lista de verificação: crie ou selecione um projeto do Google Cloud, ative a API do Google Forms, configure a tela de consentimento e crie um cliente OAuth de aplicativo de desktop.
2. Baixe o JSON desse cliente ("Baixar JSON") e dê ao assistente o caminho — set_client o armazena com acesso somente do 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-forms/credentials.json (modo 0600).

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 do Google Forms.

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

3. Autorize a conta Google que possui ou pode editar os formulários. O Playground OAuth 2.0 pode obter o token de atualização quando Usar suas próprias credenciais OAuth estiver ativado.

4. Solicite os dois escopos:

   https://www.googleapis.com/auth/forms.body
   https://www.googleapis.com/auth/forms.responses.readonly
   

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

Todas as variáveis são opcionais — sem nenhuma delas, o servidor se conecta pelo chat.

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

Dados, limites e trabalho em segundo plano

• As solicitações vão para o Google Forms. O servidor local atualiza os tokens OAuth do Google e chama a API do Forms. 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, dados de formulário, argumentos de ferramentas ou prompts. Defina ASKADS_TELEMETRY=0 para optar por não participar.
• O Google aplica cotas por minuto. Os limites documentados são 975 leituras por projeto, 450 chamadas list_responses e 375 gravações. Em 429, o servidor usa backoff; leituras também são repetidas após erros de rede e 5xx, enquanto gravações não são reproduzidas após uma falha incerta.
• Não há sondagem em segundo plano. O servidor executa apenas quando chamado. Os monitoramentos do Pub/Sub podem notificar sua própria infraestrutura sobre novas respostas; se seu aplicativo de IA suportar tarefas agendadas, ele também pode verificar respostas 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 Forms

Suporte

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

Você chegou ao fim!