# mcp-server-google-forms
[](https://www.npmjs.com/package/mcp-server-google-forms)
[](https://registry.modelcontextprotocol.io/?q=mcp-server-google-forms)
[](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](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](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](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](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](LICENSE)