# mcp-server-google-forms **Category:** 💻 Developer Tools **Repository:** https://github.com/claude-book/mcp-server-google-forms **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/mcp-server-google-forms ## Description Cria, edita e publica Google Forms a partir do Claude: quizzes, seções e leitura de respostas. ## Claude Desktop Quick Installation Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "mcp-server-google-forms": { "command": "npx", "args": ["-y","mcp-server-google-forms"] } } ``` ## Documentation & README # mcp-server-google-forms [![npm](https://img.shields.io/npm/v/mcp-server-google-forms?label=npm&color=cb3837)](https://www.npmjs.com/package/mcp-server-google-forms) [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.claude--book-6d3fc0)](https://registry.modelcontextprotocol.io/?q=mcp-server-google-forms) [![DOI](https://zenodo.org/badge/1294358395.svg)](https://doi.org/10.5281/zenodo.21296975) Servidor MCP local que permite ao Claude Code **criar, editar e publicar Google Forms** — apresentado aos usuários como **"Forms IA (MCP)"**, um app **verificado pelo Google**. Código de exemplo do livro sobre Claude Code. > ✅ **Ficou fácil:** você **não precisa criar nada no Google Cloud** nem baixar arquivos de credenciais. > É instalar, entrar com a sua conta Google (tela limpa, sem avisos) e usar. Há também uma > [versão em página, com cards](https://claude-book.github.io/mcp-server-google-forms/) — talvez mais confortável de ler. ## Índice - [Início rápido](#início-rápido) - [Guia completo para quem não programa](#guia-completo-para-quem-não-programa) - [Ferramentas (15)](#ferramentas-15) - [Solução de problemas](#solução-de-problemas) - [Usar o próprio projeto do Google Cloud (avançado)](#usar-o-próprio-projeto-do-google-cloud-avançado) - [Referência técnica](#referência-técnica) - [Documentação](#documentação) - [Citação](#citação) · [Licença](#licença) --- ## Início rápido Tem Node.js 18+, o Claude Code e uma conta Google? Então são **dois comandos**: ```bash # 1. Autorize com o Google (o navegador abre; app verificado, sem avisos) npx -p mcp-server-google-forms mcp-server-google-forms-token # 2. Registre no Claude Code claude mcp add google-forms -- npx mcp-server-google-forms ``` Quer o passo a passo detalhado, escrito para quem não programa? Siga o guia abaixo. 👇 --- ## Guia completo para quem não programa ### Pré-requisitos 1. **Node.js 18 ou mais novo.** É o programa que faz o servidor rodar; os comandos `npm` e `npx` vêm junto com ele. Para conferir, abra o terminal (veja abaixo) e digite `node --version`. Se aparecer `v18…` ou maior, está pronto. Se não, baixe a versão **LTS** em [nodejs.org](https://nodejs.org) e instale (é só avançar/próximo). 2. **O Claude Code instalado** — é por ele que você conversa com o servidor ([code.claude.com/docs](https://code.claude.com/docs)). 3. **Uma conta Google** (a mesma em que os formulários vão aparecer). **Como abrir o terminal** (é onde você cola os comandos): - **Windows:** menu Iniciar → digite *PowerShell* → abra o **Windows PowerShell**. - **Mac:** aperte `Cmd + Espaço`, digite *Terminal* e dê Enter. - **Linux:** procure por *Terminal* no menu de aplicativos (ou `Ctrl + Alt + T`). > 💡 Neste guia, "rode o comando X" significa sempre: abra o terminal, cole o `X` e aperte **Enter**. ### Passo 1 — Autorize com a sua conta Google 1. **Rode o comando de autorização:** ``` npx -p mcp-server-google-forms mcp-server-google-forms-token ``` O navegador abre sozinho na tela de login do Google. 2. **Entre com a sua conta e permita o acesso.** A tela mostra o app **Forms IA (MCP)** — verificado pelo Google, sem avisos de segurança. Confira as permissões (criar/editar formulários e ler respostas) e clique em **Continuar/Permitir**. No terminal aparece *"Pronto. refreshToken salvo…"* — deu certo. ### Passo 2 — Registre no Claude Code ``` claude mcp add google-forms -- npx mcp-server-google-forms ``` ### Passo 3 — Peça ao Claude Pronto! Abra o Claude Code e peça em português, por exemplo: > *"Crie um quiz de 5 perguntas sobre fotossíntese, valendo 2 pontos cada, e me dê o link para compartilhar."* Fluxo típico: `build_form` (ou `create_form` → `add_question`) → compartilhar o link de resposta → `list_responses`. > **Sobre publicação:** verificamos na prática (10/07/2026) que a API cria formulários **já publicados** por padrão, > ao contrário do que a documentação do Google sugeria. Por isso as ferramentas de criação aceitam `unpublished=true` > (criar como rascunho) e **informam o estado real** devolvido pela API — e o `set_publish` cobre os dois sentidos. ### Usar em outro computador É só repetir os Passos 1 e 2 na máquina nova — sem arquivos, sem configuração. Atalho para quem não quer refazer o login: copie a pasta `~/.config/mcp-server-google-forms/` (no Windows, `C:\Users\SeuNome\.config\mcp-server-google-forms\`) do computador antigo para o mesmo lugar no novo — o `config.json` dentro dela guarda a sua autorização.
🤔 Por que essa pasta fica "oculta"? O caminho começa com um ponto (`.config`) e, por isso, a pasta não aparece por padrão no Explorer (Windows) nem no Finder (Mac). Isso é intencional: programas guardam suas configurações em pastas agrupadas em `~/.config` (o `~` representa a sua pasta de usuário), fora da vista, para não poluir os seus documentos. "Oculta" não significa "protegida" — a pasta é sua e pode ser aberta a qualquer momento: cole o caminho na barra de endereço do Explorer, ou use `Cmd + Shift + G` no Finder. É ali que o servidor guarda a sua autorização (`config.json`).
💻 Prefere clonar o repositório? (para quem for mexer no código) 1. **Clone e instale:** ``` git clone https://github.com/claude-book/mcp-server-google-forms.git cd mcp-server-google-forms npm install ``` 2. **Autorize:** rode `npm run token` e aprove no navegador. 3. **Registre no Claude Code** (rodando na raiz do projeto): ``` claude mcp add google-forms -- node "$(pwd)/src/server.js" ```
--- ## Ferramentas (15) | Ferramenta | O que faz | | --- | --- | | `create_form` | Cria um formulário e devolve o ID e os links. Por padrão o Google o cria **já publicado**; use `unpublished=true` para rascunho. A resposta informa o estado real. | | `build_form` | Cria o formulário **inteiro numa única operação**: título, descrição, modo quiz e todas as perguntas. | | `set_publish` | Publica ou despublica o formulário (libera ou bloqueia respostas). | | `get_form` | Mostra a lista de itens com as posições e a estrutura completa. | | `add_question` | Acrescenta uma pergunta (no final ou numa posição). Nove tipos: texto curto/longo, escolha única, caixas de seleção, lista suspensa, escala linear, data, hora/duração e avaliação (estrelas, corações ou joinhas). | | `update_form_info` | Altera o título e/ou a descrição de um formulário existente. | | `update_question` | Edita uma pergunta existente (enunciado, obrigatoriedade, alternativas, pontos, gabarito) sem apagar e recriar — preserva o vínculo com respostas já recebidas. | | `set_quiz` | Liga ou desliga o modo quiz (com notas). Obrigatório antes de usar `points`. | | `add_section` | Insere uma quebra de seção (nova página) na posição indicada. | | `add_text_item` | Insere um bloco de texto explicativo (sem campo de resposta) na posição indicada. | | `delete_question` | Remove a pergunta na posição indicada (recusa apagar o que não for pergunta). | | `move_question` | Move um item de uma posição para outra. | | `list_responses` | Lista as respostas, incluindo perguntas de upload de arquivo. Em páginas (padrão 50), com `pageSize`/`pageToken`. | | `verify_answer_keys` | Confere o gabarito de um quiz contra uma lista esperada (auditoria pós-criação). | | `auth_status` | Diagnóstico das credenciais: arquivo presente, campos completos e teste real com o Google. | --- ## Solução de problemas - **"Credenciais expiradas ou revogadas"** — rode o comando de autorização de novo (Passo 1) e refaça o login; o servidor recarrega as credenciais sozinho, sem precisar reiniciar. - **O navegador não abriu na autorização?** — o terminal também imprime a URL; copie e cole no navegador. - Usa o **seu próprio projeto** do Google Cloud? Os problemas específicos desse caso estão na seção abaixo. Para um diagnóstico rápido, peça ao Claude para rodar a ferramenta `auth_status`: ela testa as credenciais direto com o Google. --- ## Usar o próprio projeto do Google Cloud (avançado) Por padrão, a autorização usa a credencial embutida do app **Forms IA (MCP)**, verificado pelo Google — e a sua autorização e os seus dados continuam só na sua conta e na sua máquina (detalhes em `src/default-client.js`). Se preferir usar um projeto **seu** (por exemplo, para ter as suas próprias cotas), o app respeita: um `client_secret*.json` na pasta de credenciais **tem prioridade** sobre a credencial embutida.
Passo a passo do projeto próprio 1. Em [console.cloud.google.com](https://console.cloud.google.com): crie um projeto → ative a **Google Forms API** → configure a **Tela de permissão OAuth** (tipo Externo) → **adicione-se como usuário de teste** (sem isso, a autorização falha com "acesso negado") → crie a credencial (**ID do cliente OAuth**, tipo **App para computador**). 2. **Baixe o JSON na hora da criação** — o Google não permite baixá-lo depois (se perder, crie outro cliente). 3. Coloque o `client_secret*.json` em `~/.config/mcp-server-google-forms/` (Windows: `C:\Users\SeuNome\.config\mcp-server-google-forms\`) — ou em `credentials/`, na instalação por clone. 4. Rode o comando de autorização; o terminal confirma: *"Usando o seu projeto próprio do Google Cloud"*. **Avisos que só aparecem no projeto próprio:** - **"O Google não verificou este app"** — normal (o app é seu); clique em **Avançado → Acessar … (não seguro)**. - **"Acesso negado" / `access_denied`** — você não se adicionou como **usuário de teste**; volte à Tela de permissão. - **Expiração de 7 dias** — em modo **Testing**, o Google expira a autorização a cada 7 dias; publique o app (Tela de permissão OAuth → **Publicar app**) para resolver. Para uso pessoal não é preciso passar pela verificação.
--- ## Referência técnica
Estrutura da pasta ``` src/server.js → o servidor MCP src/default-client.js → credencial OAuth padrão (app verificado; pública por design) src/credentials-dir.js → resolução da pasta de credenciais scripts/get-token.js → autorização OAuth (rodar uma vez) credentials/ → segredos locais (config.json e, opcionalmente, client_secret*.json) — fora do git docs/ → site do projeto (GitHub Pages) ```
Onde ficam as credenciais O servidor e o script de autorização procuram as credenciais nesta ordem: 1. Na pasta definida pela variável de ambiente `GOOGLE_FORMS_MCP_DIR`, se houver; 2. Em `credentials/` dentro do projeto, se a pasta existir (instalação por clone); 3. Em `~/.config/mcp-server-google-forms/` (instalação via npm/npx). Na autorização, um `client_secret*.json` presente na pasta tem prioridade; sem ele, usa-se a credencial embutida do app verificado (`src/default-client.js`).
Arquivos sensíveis O que é secreto de verdade é o `config.json` (guarda o seu refresh token) — ele nunca sai da sua máquina e a pasta `credentials/` do clone está no `.gitignore`. A credencial embutida (`src/default-client.js`) é de um cliente OAuth do tipo **Desktop**, que o Google trata como **não-secreta** (modelo rclone/gcloud): a segurança do fluxo vem do consentimento do usuário no navegador, não do sigilo desse valor.
--- ## Documentação - [Página do projeto](https://claude-book.github.io/mcp-server-google-forms/) — apresentação, [política de privacidade](https://claude-book.github.io/mcp-server-google-forms/privacidade.html) e [termos de uso](https://claude-book.github.io/mcp-server-google-forms/termos.html). - [Página do app no domínio do autor](https://henriquealvarenga.com/mcp/) — home, privacidade e termos do **Forms IA (MCP)**. - [Revisão de código](https://github.com/claude-book/mcp-server-google-forms/blob/HEAD/docs/revisao-de-codigo.md) — problemas conhecidos, gravidade, status das correções e histórico de alterações com as razões de cada mudança. - [Estudo de MCPs similares](https://github.com/claude-book/mcp-server-google-forms/blob/HEAD/docs/estudo-de-mcps-similares.md) — comparação com 7 servidores MCP para Google Forms do GitHub, melhorias adotadas e anti-padrões a evitar. - [Versão em HTML](https://github.com/claude-book/mcp-server-google-forms/blob/HEAD/docs/revisao-de-codigo.html) — o mesmo relatório em formato amigável para não-programadores (abra no navegador). ## Citação Este software tem DOI permanente (arquivado no [Zenodo](https://doi.org/10.5281/zenodo.21296975) a cada release; metadados em [CITATION.cff](https://github.com/claude-book/mcp-server-google-forms/blob/HEAD/CITATION.cff)): > Alvarenga da Silva, H. (2026). *mcp-server-google-forms: servidor MCP para Google Forms*. Zenodo. https://doi.org/10.5281/zenodo.21296975 ## Licença [MIT](https://github.com/claude-book/mcp-server-google-forms/blob/HEAD/LICENSE)