mcpField
M
mcp-server-google-forms

mcp-server-google-forms

Local
github.com/claude-bookProductivity0Updated 12w ago
Repository

About mcp-server-google-forms

A local MCP server for Claude Code that creates, edits, publishes, and reads Google Forms. It supports quizzes, structured sections, and response review, with Google account authorization through a browser.

Key features

  1. 01Create complete forms in one operation
  2. 02Add and edit nine question types
  3. 03Manage quiz mode and answer keys
  4. 04Insert sections and explanatory text
  5. 05Publish or unpublish forms
  6. 06List responses and check credentials

Use cases

  1. 01Build a quiz with questions and scoring
  2. 02Revise a form while preserving existing responses
  3. 03Organize a long form into sections
  4. 04Review submissions or audit quiz answers

MCP support

Exposes 15 Google Forms tools to MCP clients, including form creation, editing, publication, response listing, and authorization diagnostics.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "claude-book-mcp-server-google-forms": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-google-forms"
      ],
      "env": {
        "GOOGLE_FORMS_MCP_DIR": "<GOOGLE_FORMS_MCP_DIR>"
      }
    }
  }
}
Run commandnpx -y mcp-server-google-forms
Environment variables to set
GOOGLE_FORMS_MCP_DIRPasta com as credenciais do Google (client_secret*.json e config.json). Opcional — padrão: ~/.config/mcp-server-google-forms/

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npmmcp-server-google-forms0.5.0

Tools

15

Saved tool list · updated 3w ago

ParameterTypeRequiredDescription
titlestringYesForm title, visible to respondents
unpublishedbooleanNotrue to create as a draft (no one can respond until set_publish). Default: published.
documentTitlestringNoFile name in Drive (optional)

Details

From the project 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:

# 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 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.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)

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 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

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

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.