Mcp Server Google Forms

io.github.claude-bookPublished by GitHub account claude-bookv0.5.0Updated Oct 24, 2026

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

Overview

AI-generated overview

A local MCP server that lets an assistant create, edit, publish and read responses of Google Forms, including quizzes with sections and answer keys.

What you can do
Create forms in one call or step by step, with title, description, quiz mode and questions of nine types, plus sections and explanatory text blocks, and publish or unpublish them to open or close responses. Read a form's structure and item positions, then edit title, description, questions, options, points and answer keys, or move and delete items. List responses page by page, including file-upload answers. Audit a quiz's answer keys against an expected list and check credential status with a real call to Google.
When to use it
Useful when you want to draft, restructure or publish Google Forms and quizzes from a conversation, or pull collected responses into the chat without opening the Forms editor.
Requirements
Runs locally via npx with Node.js 18 or newer, Claude Code and a Google account. A one-time browser authorization command stores a refresh token in a credentials folder, which can be relocated with the GOOGLE_FORMS_MCP_DIR environment variable; optionally a user-supplied client_secret JSON for a personal Google Cloud project.
Before you install
The stored config.json holds a refresh token granting create/edit access to forms and read access to responses; it stays on the machine but copying the credentials folder to another computer copies that authorization. Creating forms publishes them by default unless a draft is requested, and delete and move tools change existing forms. The default authorization uses the author's embedded OAuth client, so form data flows through Google under that app's identity.

Installation

In SourceWeft

  1. Open Mcp Server Google Forms in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

mcp-server-google-forms

[npm] [MCP Registry] [DOI]

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 — talvez mais confortável de ler.

Índice


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 Codeclaude 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 e instale (é só avançar/próximo).
  2. O Claude Code instalado — é por ele que você conversa com o servidor (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.gitcd mcp-server-google-formsnpm 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)

FerramentaO que faz
create_formCria 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_formCria o formulário inteiro numa única operação: título, descrição, modo quiz e todas as perguntas.
set_publishPublica ou despublica o formulário (libera ou bloqueia respostas).
get_formMostra a lista de itens com as posições e a estrutura completa.
add_questionAcrescenta 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_infoAltera o título e/ou a descrição de um formulário existente.
update_questionEdita uma pergunta existente (enunciado, obrigatoriedade, alternativas, pontos, gabarito) sem apagar e recriar — preserva o vínculo com respostas já recebidas.
set_quizLiga ou desliga o modo quiz (com notas). Obrigatório antes de usar points.
add_sectionInsere uma quebra de seção (nova página) na posição indicada.
add_text_itemInsere um bloco de texto explicativo (sem campo de resposta) na posição indicada.
delete_questionRemove a pergunta na posição indicada (recusa apagar o que não for pergunta).
move_questionMove um item de uma posição para outra.
list_responsesLista as respostas, incluindo perguntas de upload de arquivo. Em páginas (padrão 50), com pageSize/pageToken.
verify_answer_keysConfere o gabarito de um quiz contra uma lista esperada (auditoria pós-criação).
auth_statusDiagnó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: 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 MCPsrc/default-client.js   → credencial OAuth padrão (app verificado; pública por design)src/credentials-dir.js  → resolução da pasta de credenciaisscripts/get-token.js    → autorização OAuth (rodar uma vez)credentials/            → segredos locais (config.json e, opcionalmente, client_secret*.json) — fora do gitdocs/                   → 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

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

Source: README.md at commit cb6652e

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.5.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts