Server Google Forms

БесплатноНе проверен

Cria, edita e publica Google Forms a partir do Claude: quizzes, seções e leitura de respostas.

автор: io.github.claude-book

GitHub Embed

Описание

Cria, edita e publica Google Forms a partir do Claude: quizzes, seções e leitura de respostas.

README

npm MCP Registry DOI

Servidor MCP local que permite ao Claude Code criar, editar e publicar Google Forms. Código de exemplo do livro sobre Claude Code — instale pelo npm (ou clone), autorize com a sua conta Google e use.

🧑‍🏫 Nunca mexeu com terminal? O guia abaixo foi escrito para quem não programa: é só copiar e colar. Você faz esta configuração uma única vez; depois, é só conversar com o Claude. Há também uma versão em página, com cards — talvez mais confortável de ler.

Início rápido

Já tem Node.js 18+, o Claude Code e um client_secret*.json (OAuth "App para computador") do Google Cloud? Então são três passos:

# 1. Coloque o client_secret*.json em ~/.config/mcp-server-google-forms/
#    (rode o comando abaixo uma vez e ele cria essa pasta sozinho)

# 2. Autorize com o Google
npx -p mcp-server-google-forms mcp-server-google-forms-token

# 3. Registre no Claude Code
claude mcp add google-forms -- npx mcp-server-google-forms

Nunca configurou o projeto no Google Cloud, ou quer o passo a passo detalhado? Siga o guia abaixo. 👇

Guia completo para quem não programa

Antes de começar (o que você precisa ter)

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 e instale (é só avançar/próximo).
O Claude Code instalado — é por ele que você conversa com o servidor (code.claude.com/docs).
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).

Passo 1 — Preparar o Google Cloud (uma vez)

Isto autoriza o servidor a falar com o Google Forms em seu nome. Parece longo, mas você faz só uma vez. Acesse console.cloud.google.com e faça login com a sua conta Google.

Crie um projeto. No topo da página, clique no seletor de projetos → Novo projeto → dê um nome (ex.: meus-forms) → Criar. Depois, confira que ele está selecionado no topo.
Ative a Google Forms API. Na barra de busca do topo, procure por Google Forms API, abra o resultado e clique em Ativar.
Configure a tela de permissão. No menu (☰) → APIs e serviços → Tela de permissão OAuth. Escolha o tipo Externo → Criar. Preencha o nome do app (ex.: Meus Forms), o e-mail de suporte e o e-mail de contato do desenvolvedor (pode ser o seu mesmo) → salve avançando as telas.
Adicione-se como usuário de teste — este é o passo que mais gente esquece. Ainda na Tela de permissão, na seção Usuários de teste, clique em Adicionar usuários e coloque o seu próprio e-mail do Google. Sem isso, o Google recusa a autorização com "acesso negado".
Crie a credencial. No menu → APIs e serviços → Credenciais → Criar credenciais → ID do cliente OAuth → em "Tipo de aplicativo" escolha App para computador → Criar.
Baixe o arquivo. Na janela que aparece (ou no ícone de download ⬇ ao lado da credencial), clique em Fazer download do JSON. Esse é o seu client_secret*.json. Guarde-o — você vai usá-lo no Passo 2.

Passo 2 — Instalar e autorizar (Caminho A, recomendado)

Sem clonar nada, direto pelo npm:

Rode o comando de autorização uma primeira vez. Ele ainda vai falhar de propósito — mas já cria a pasta certa e mostra o caminho dela. No terminal, cole:
```
npx -p mcp-server-google-forms mcp-server-google-forms-token
```
Vai aparecer uma mensagem como "Não encontrei nenhum 'client_secret.json' em …/.config/mcp-server-google-forms"*. Anote (ou copie) esse caminho — é para lá que vai o arquivo.
Coloque o client_secret*.json naquela pasta. Ela é oculta, então use o atalho de "ir para a pasta":
- Windows: no Explorer, clique na barra de endereço, cole %USERPROFILE%\.config\mcp-server-google-forms e dê Enter.
- Mac: no Finder, Cmd + Shift + G, cole ~/.config/mcp-server-google-forms e dê Enter. Arraste o arquivo para lá.
- Linux: no gerenciador de arquivos, Ctrl + L, cole ~/.config/mcp-server-google-forms e dê Enter.
Rode o mesmo comando de novo. Agora o navegador abre sozinho:
```
npx -p mcp-server-google-forms mcp-server-google-forms-token
```
- Escolha a sua conta Google.
- Vai aparecer a tela "O Google não verificou este app". Isso é normal (o app é seu e está em modo de teste). Clique em Avançado → Acessar Meus Forms (não seguro). Pode confiar: é o seu próprio app, rodando na sua máquina.
- Confirme as permissões. No terminal aparece "Pronto. refreshToken salvo…" — deu certo.

Registre no Claude Code:

claude mcp add google-forms -- npx mcp-server-google-forms

🤔 Por que a 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 costumam guardar suas configurações — preferências, credenciais, chaves de acesso — em uma pasta reservada, para não espalhar arquivos pela sua pasta de usuário. Por convenção, essas pastas ficam agrupadas em ~/.config (o ~ representa a sua pasta de usuário), e o ponto no início do nome faz o sistema não exibi-las na navegação normal. No Windows, o caminho equivalente é C:\Users\SeuNome\.config\mcp-server-google-forms, e essa pasta também fica oculta por padrão.

"Oculta" não significa "protegida": a pasta é sua e pode ser aberta a qualquer momento — foi o que fizemos ao colar o caminho na barra de endereço. O ponto apenas evita que ela apareça junto dos seus documentos. É o local padrão onde ferramentas de linha de comando esperam encontrar esse tipo de arquivo, e por isso o servidor guarda ali o seu client_secret.json e a autorização.

💻 Caminho B — via clone do repositório (para quem for mexer no código)

Clone e instale:

git clone https://github.com/claude-book/mcp-server-google-forms.git
cd mcp-server-google-forms
npm install

Coloque o client_secret*.json na pasta credentials/ dentro do projeto (crie-a se não existir).
Autorize: rode npm run token e aprove no navegador (mesma tela do Google descrita no Caminho A, incluindo o aviso de "app não verificado"). Isso gera credentials/config.json.

Registre no Claude Code (rodando na raiz do projeto):

claude mcp add google-forms -- node "$(pwd)/src/server.js"

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.

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

"O Google não verificou este app" (tela laranja durante a autorização)

É esperado enquanto o seu app OAuth está em modo Testing. Clique em Avançado → Acessar … (não seguro). É o seu próprio app; não há risco.

"Acesso negado" / access_denied ao autorizar

Quase sempre é porque você não se adicionou como usuário de teste (Passo 1.4). Volte à Tela de permissão OAuth, adicione o seu e-mail em Usuários de teste e tente de novo.

"Credenciais expiradas ou revogadas"

Rode o comando de autorização de novo (npm run token no clone, ou npx -p mcp-server-google-forms mcp-server-google-forms-token no npm) e repita; o servidor recarrega as credenciais sozinho, sem precisar reiniciar. Importante: enquanto o app OAuth estiver em modo Testing no Google Cloud, o Google expira a autorização a cada 7 dias. Para tokens duradouros, publique o app (Tela de permissão OAuth → In production).

"O Google não enviou o refresh token"

Se a mensagem pedir, remova o acesso deste app em myaccount.google.com/permissions e rode a autorização mais uma vez.

Para um diagnóstico rápido, peça ao Claude para rodar a ferramenta auth_status: ela testa as credenciais direto com o Google.

Referência técnica

Estrutura da pasta

src/server.js          → o servidor MCP
scripts/get-token.js   → autorização OAuth (rodar uma vez)
credentials/           → segredos locais (client_secret*.json e config.json) — fora do git
docs/                  → revisão de código e histórico de alterações

Onde ficam as credenciais

O servidor e o script de autorização procuram as credenciais nesta ordem:

Na pasta definida pela variável de ambiente GOOGLE_FORMS_MCP_DIR, se houver;
Em credentials/ dentro do projeto, se a pasta existir (instalação por clone);
Em ~/.config/mcp-server-google-forms/ (instalação via npm/npx).

Arquivos sensíveis

Tudo na pasta de credenciais guarda segredos — no caso do clone, a pasta credentials/ inteira está no .gitignore e nunca deve ser commitada. O pacote npm é gerado só com src/ e scripts/ (campo files do package.json), então credenciais jamais entram no pacote.

Documentação

Página do projeto — apresentação, política de privacidade e termos de uso.
Revisão de código — 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 — comparação com 7 servidores MCP para Google Forms do GitHub, melhorias adotadas e anti-padrões a evitar.
Versão em 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 a cada release; metadados em 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

from github.com/claude-book/mcp-server-google-forms

Установить Server Google Forms в Claude Desktop, Claude Code, Cursor

Рекомендуется · одна команда, все IDE

unyly install mcp-server-google-forms

Ставит в Claude Desktop, Claude Code, Cursor и VS Code — сам разбирается с npx, uvx и сборкой из исходников.

Впервые? Поставь CLI: curl -fsSL https://unyly.org/install | sh

Или настроить вручную

Выполни в терминале:

claude mcp add mcp-server-google-forms -- npx -y mcp-server-google-forms

FAQ