This MCP server connects an AI to Coletum form data so it can read forms/fillings and generate local Excel, CSV, and PDF outputs without changing anything in Coletum.
List forms and inspect their structure: fields, labels, types, options, rules, and groups.
Count and search fillings with filters for date, origin, author, and editor.
Export fillings to XLSX or CSV in Coletum’s standard layout, with adjustments such as selected/hidden fields, single-sheet mode, labels, CSV separator/decimal, and metadata placement.
Generate Coletum-style PDFs: standard export layout, column/compact layout, or photographic report, with options like logo, hidden fields, photos per row, font size, highlight color, and orientation.
Analyze a client’s PDF/photo model, generate PDFs from custom Typst templates, compare side-by-side, and save reusable models.
Manage local preferences and models: read/save preferences, list built-in and saved PDF models, and show templates.
Open generated files/folders in the system file browser.
Respect API quota/rate limits and keep Coletum access read-only; outputs are written only to local folders.
Provides a migration tool that converts code, Power BI queries, or scripts still using the Coletum API V1 (GraphQL) to the API V2, ahead of the V1 shutdown date.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Coletum MCP Server exporte em Excel os preenchimentos de setembro da vistoria"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Plugin que liga a sua IA (Claude ou ChatGPT) aos dados dos seus formulários do Coletum. Você pede em português, a IA lê os dados e entrega o arquivo pronto: planilha ou PDF. O conector só lê os dados (nunca altera nada no Coletum).
O conector oferece 14 ferramentas à IA, que você usa conversando:
Ler formulários e preenchimentos: listar seus formulários, ver a estrutura de cada um, contar e buscar preenchimentos por período, origem (aplicativo, sistema ou link público) ou autor.
Excel e CSV: exportar os preenchimentos no mesmo padrão da exportação do Coletum, com ajustes pedidos na conversa (só alguns campos, tudo numa aba, CSV com vírgula).
PDF no padrão do Coletum: o PDF igual ao da exportação, com ajustes (seu logo, tirar campos, fotos por linha, cor, página deitada), ou em colunas, ou relatório fotográfico. Sem pedido, o cabeçalho traz o nome e o logo da conta, como a exportação (conta sem logo: o do Coletum); com outro logo, ele substitui.
PDF no seu modelo: você mostra o documento que a sua empresa já usa (um PDF, um Word salvo em PDF ou uma foto do papel) e a IA gera os preenchimentos nesse layout, compara com o original, ajusta e guarda o modelo para reusar.
Arquivos e preferências: o conector guarda o que você prefere (logo, nome da empresa) e mostra onde cada arquivo foi gravado.
Quatro roteiros prontos (skills) guiam a IA em cada tarefa: /coletum:planilha, /coletum:pdf, /coletum:pdf-no-modelo e
/coletum:migrar-v1, que converte para a API V2 um script, consulta do Power BI ou código que ainda usa a API V1 (GraphQL),
que sai do ar em 01/11/2026, mantendo o mesmo resultado.
Related MCP server: Formester
No Claude, funciona no Claude Code: na aba Code do Claude Desktop (Mac ou Windows) e no terminal. No Chat e no Cowork o conector ainda não roda (eles não executam conector local de plugin). No ChatGPT, veja No ChatGPT.
Precisa de: acesso de administrador no Coletum e, no Claude, um plano pago.
Entre no Coletum com uma conta de administrador.
Vá em Menu principal > Web Service.
Clique em Adicionar Token (ou Criar meu primeiro token, se for o primeiro), dê um nome (por exemplo, "IA") e salve.
Copie o token (ele fica disponível na tela Web Service, no cartão com o nome que você deu).
Claude Desktop (sem terminal):
No Windows: instale o Git antes. No PowerShell, rode winget install --id Git.Git -e --source winget (ou use o
instalador de git-scm.com) e feche e abra o Claude Desktop depois de instalar. Sem
o Git, a opção Adicionar marketplace não aparece. No Mac, pule este passo.
Abra Personalização e vá em Plugins.
Clique em Adicionar e depois em Adicionar marketplace. Informe geo-sapiens/coletum-mcp.
Clique em Sincronizar.
No plugin Coletum MCP, clique em Adicionar e depois em Continuar. Aparece o aviso "Este plugin inclui servidores MCP locais": é o conector, que roda no seu computador.
O plugin fica instalado na sua conta, e o conector roda na aba Code (não precisa escolher pasta). No Chat e no Cowork o conector não roda.
Claude Code no terminal:
/plugin marketplace add geo-sapiens/coletum-mcp
/plugin install coletum@coletum-mcpAbra uma conversa nova e peça: "liste meus formulários do Coletum".
Token: pelo terminal, a instalação já pediu o token. Pela aba Code do Desktop, o Claude avisa que falta o token: cole o token na conversa, o conector testa com 1 chamada e guarda no cofre do sistema (Keychain no Mac, Credential Manager no Windows). Nas próximas conversas não pede mais. O token fica escrito no histórico daquela conversa: ele é só de leitura, e você pode desativar e gerar outro no Coletum quando quiser.
Aparece a lista dos formulários da conta.
Peça em português, por exemplo:
"Exporta para Excel os preenchimentos desta semana do formulário NOME DO FORMULÁRIO"
"Só os campos X e Y", "tudo numa aba só", "em CSV", "dos últimos 7 dias"
"Gera o PDF dos 3 mais recentes", "põe meu logo e tira o campo Observações", "relatório fotográfico"
Os arquivos ficam em Documentos/Coletum (planilhas e PDFs em saidas/, modelos em modelos/), e a IA mostra o
caminho completo. Para outra pasta, diga no pedido ("salva na pasta X"). Para abrir, peça "abre o arquivo".
Na primeira vez, o conector prepara o que precisa para rodar e leva alguns instantes a mais. Ele usa o uv
(gerenciador de Python da Astral): se o uv não estiver instalado, o conector baixa o instalador oficial
(astral.sh/uv/install.sh) e instala o uv só dentro da pasta de dados do plugin, sem senha de administrador e sem
alterar o sistema. Depois, o uv baixa o Python e as bibliotecas do conector (uns 60 MB, uma vez).
Windows, no Claude Code: o conector sobe pelo git, então precisa do Git instalado (ver o passo "No Windows:
instale o Git antes"; pelo terminal vale o mesmo). Testado num Windows 11 limpo. Na primeira conversa, o conector baixa o
que precisa (1 a 3 minutos) e o Claude pode desistir antes, com tempo esgotado: feche e abra o Claude e peça de novo.
Depois disso ele sobe em poucos segundos. Num Mac sem as ferramentas de desenvolvedor da Apple, a primeira subida pede
para instalá-las (é o que traz o git).
Funciona no app do ChatGPT para Windows e Mac, sem instalar mais nada além do app. Passo a passo, com telas: guia do ChatGPT.
Abra Plugins, clique em Adicionar e depois em Adicionar marketplace (no app em inglês: Plugins > Add > Add a
marketplace). Em Origem, informe geo-sapiens/coletum-mcp e, em Referência do Git, main.
Na aba Pessoais, instale o plugin Coletum MCP, feche o app por completo e abra de novo.
Numa conversa nova no Work (ou no Codex, se você usa), peça "liste meus formulários do Coletum". No Chat o conector pode não aparecer. O conector pede o token: cole o token gerado no passo 1. Ele testa e guarda no cofre do sistema, como no Claude.
A primeira conversa demora alguns minutos: o conector baixa o que precisa para rodar. Só na primeira vez.
Claude Code: marketplace de terceiros vem com a atualização automática desligada. Para pegar a versão nova, rode:
/plugin marketplace update coletum-mcpou, em /plugin, abra Marketplaces, escolha coletum-mcp e ative Enable auto-update.
ChatGPT: atualiza sozinho. Ao abrir, o app busca a versão nova no marketplace e reinstala o plugin.
As mudanças de cada versão estão no CHANGELOG.
O conector é um servidor MCP comum (stdio) e funciona em qualquer cliente MCP. Com o uv instalado e este repositório baixado, o comando é:
uv run --project /caminho/para/coletum-mcp python /caminho/para/coletum-mcp/server/server.pycom estas variáveis de ambiente:
Variável | Para quê |
| token do Webservice V2 (obrigatória) |
| pasta dos arquivos: saídas em |
| pastas separadas, se preferir (valem por cima de |
| intervalo mínimo, em segundos, entre o início de duas requisições (opcional; padrão 0,5) |
| teto de chamadas por hora, janela móvel (opcional; padrão 300) |
Os roteiros da pasta skills/ também chegam a esses clientes como prompts do servidor (coletum-planilha, coletum-pdf, coletum-pdf-no-modelo, coletum-migrar-v1).
Hoje, enquanto a API v1 existir, cada chamada à API v2 do Coletum consome 0,2 da cota mensal da conta (5 chamadas = 1 unidade da cota); essa regra pode mudar quando a v1 sair. Cada página lida conta; chamada com erro não conta. Toda ferramenta informa chamadas_api e cota_consumida (calculada com o peso atual), e a IA conta os preenchimentos antes de exportar para avisar o custo; a contagem traz também o saldo real da cota do mês, lido da API sem gastar cota. Baixar as fotos dos anexos não gasta cota.
Para proteger a cota contra rajadas, o conector:
espera 0,5 s entre o início de duas chamadas (COLETUM_INTERVALO_S muda o intervalo);
recusa, antes de chamar, passar de 300 chamadas por hora (janela móvel, somando todas as conversas; COLETUM_MAX_CHAMADAS_HORA muda o teto). Os horários ficam num arquivo pequeno, .uso_api.json, na pasta dos arquivos;
identifica o uso com o cabeçalho User-Agent: coletum-mcp/<versão> em toda requisição.
O conector roda no seu computador e fala direto com a API do Coletum. Nada passa por servidor nosso.
Ele só lê os dados. Só grava arquivos na pasta que você escolheu.
O token fica no cofre de credenciais do sistema (cofre de credenciais do Mac, do Windows ou do Linux) e nunca é impresso.
Planilhas e PDFs são gerados pelo conector: o conteúdo dos preenchimentos e as fotos não passam pela conversa, só o caminho do arquivo e as contagens.
No Claude Code, o .mcp.json chama o scripts/iniciar.sh por um alias do git (git -c alias.coletum=!sh ... coletum):
é o único comando que serve no Mac e no Windows. O porquê está no cabeçalho do iniciar.sh.
Os testes rodam sem API e sem rede:
uv run python server/teste_pastas.py
uv run python server/teste_subida.py
uv run python server/teste_limites.py
uv run python server/teste_token.py
uv run python server/teste_estrela_data.py
uv run python server/teste_versoes.py
uv run python server/teste_lancadores.py
uv run python server/teste_busca_bucket_ua.pyTeste de conversa (10 pedidos em português num claude -p com este plugin, só contra o Coletum local, confere a ferramenta e os parâmetros chamados):
COLETUM_TOKEN=<token local> python3 teste_conversa/rodar.py (o uso completo está no topo do rodar.py).
Código sob a licença MIT, © GeoSapiens. A fonte Noto Sans, que vai junto nos modelos, segue a licença dela (SIL Open Font License, em server/modelos/_fontes/OFL.txt). "Coletum" é marca da GeoSapiens; a licença do código não cede a marca.
Analisa o PDF modelo do cliente para replicar o layout num template Typst.
Devolve JSON compacto (tamanho da página em mm, margens estimadas, linhas de texto com posição, fonte, tamanho, estilo e cor, cores dominantes do texto, das áreas preenchidas e das linhas, imagens embutidas com posição e tamanho) E as páginas renderizadas como imagem, para você ver o layout. As imagens embutidas são salvas em disco (candidatas a logo, com o caminho) para usar em gerar_pdf_modelo e salvar_modelo (arquivos). Foto do papel: só a imagem, sem texto extraído. Só lê o arquivo indicado. Não chama a API.
Inputs: caminho (required), paginas, resolucao, pasta_saida.
Traz UMA página de preenchimentos em resumo compacto, para a IA ler.
Cada preenchimento vem com id, data, autor, origem, coordenada do aparelho, os campos simples preenchidos (pelo rótulo), quantos itens tem cada grupo repetível e quantos anexos. Os links dos anexos e os itens dos grupos ficam de fora: para isso, use exportar_preenchimentos. Os preenchimentos vêm do mais recente para o mais antigo (data de criação). Os N mais recentes: pagina=1 e tamanho_pagina=N (1 chamada). Os mais antigos: use contar_preenchimentos e leia a última página. Custo: 1 chamada por página (a estrutura do formulário custa mais 1 na primeira vez). Para ler a próxima página, chame de novo com pagina+1 enquanto tem_proxima for verdadeiro. Para muitos preenchimentos, prefira exportar_preenchimentos.
Inputs: id_formulario (required), origem, pagina, criado_por, +6 more.
Conta quantos preenchimentos batem com os filtros, sem trazê-los.
Custo: sempre 1 chamada (pede 1 preenchimento só para ler o total). Use SEMPRE antes de buscar ou exportar: devolve o total e quantas chamadas (e quanta cota, com o peso atual da v2) custaria ler tudo na conversa (páginas de tamanho_pagina) ou exportar para arquivo (páginas de 500). Filtro inválido é recusado antes de chamar a API.
Inputs: id_formulario (required), origem, criado_por, editado_por, +5 more.
Estrutura de um formulário: campos em ordem, com chave técnica, rótulo, tipo, se é múltiplo, se é obrigatório, opções dos campos de escolha, regras de exibição e grupos (repetíveis ou não).
Use antes de montar planilha ou PDF: dá os rótulos legíveis, a ordem e os blocos. Custo: 1 chamada na primeira vez; depois fica guardada em memória e custa 0 enquanto o servidor roda.
Inputs: id_formulario (required), max_opcoes, forcar_atualizacao.
Exporta os preenchimentos filtrados para planilha no disco, no mesmo padrão da exportação do Coletum.
Sem ajustes, o arquivo é o que o cliente já conhece: aba LEIA-ME, aba do formulário (1 linha por preenchimento, código, campos, contagem dos grupos e das fotos, metadados no fim) e uma aba por grupo repetível ou campo com várias respostas, ligadas pelos códigos (1.2, 1.2.0, 1.2.0.1) e por links internos. O CSV é o mesmo conjunto em arquivos: ponto e vírgula, vírgula decimal, UTF-8 com BOM. Com ajustes: escolher campos, aba única (modo linhas ou colunas), metadados no começo ou fora, rótulos, CSV com vírgula e ponto, extras. Ajuste inválido é recusado antes de ler os preenchimentos. Custo: 1 chamada por página de 500, mais 1 pela estrutura na primeira vez. Para em max_paginas e avisa se ficou preenchimento de fora. Devolve só o caminho, o link, as contagens e o consumo da cota, nunca o conteúdo (CSV: o link da pasta e o de cada arquivo). Rode contar_preenchimentos antes para saber quantas chamadas vai gastar. Ao terminar, sempre mostre ao usuário o caminho completo de cada arquivo (vem no começo da resposta e em mostrar_ao_usuario), em bloco de código, para ele copiar; se ele pedir para abrir, use mostrar_arquivo. Nunca diga só 'na pasta do projeto'.
Inputs: id_formulario (required), origem, ajustes, formato, +10 more.
Gera PDF de um ou vários preenchimentos a partir de um template Typst (modelo salvo, arquivo .typ ou texto).
Os modelos do Coletum (coletum_exportacao, o PDF padrão; coletum_colunas; coletum_fotografico) saem mais simples por gerar_pdf_preenchimento. Aqui entram o modelo do cliente e o template em teste; aparencia leva os mesmos ajustes (campos, fotos por linha, fonte, cor de destaque, orientação) para os modelos que a leem.
Monta a pasta do trabalho (dados.json no contrato versão 1, fotos já baixadas, arquivos e fontes do modelo, coletum.typ) e compila com o Typst, com a raiz nessa pasta: o template não lê nada fora dela e não baixa pacotes. Erro de compilação volta com a mensagem do Typst, linha e coluna, para corrigir o template e gerar de novo. Escolha dos preenchimentos igual à de gerar_pdf_preenchimento (só com filtros, entram os mais recentes: "os 5 últimos" = max_preenchimentos=5). Com comparar_com, devolve a imagem lado a lado para comparar com o modelo do cliente. Salve o modelo aprovado com salvar_modelo e depois gere só pelo nome. Custo: 1 chamada por janela de busca ou página de filtro, mais 1 pela estrutura na 1ª vez; fotos não gastam cota. Links: o de cada PDF (com mais de um, também o da pasta) e o do lado a lado. Ao terminar, sempre mostre ao usuário o caminho completo de cada arquivo (vem no começo da resposta e em mostrar_ao_usuario), em bloco de código, para ele copiar; se ele pedir para abrir, use mostrar_arquivo. Nunca diga só 'na pasta do projeto'.
Inputs: id_formulario (required), logo, modo, modelo, +17 more.
Gera PDF de preenchimentos. O PDF padrão é o da exportação do Coletum (modelo coletum_exportacao, o mesmo de gerar_pdf_modelo); a resposta traz modelo e layout. Os ajustes pedidos na conversa ("põe meu logo", "tira o campo X", "uma foto por linha", fonte, cor de destaque, página deitada) valem NO PRÓPRIO modelo do Coletum: o visual continua o da exportação. modelo=coletum_colunas para "em colunas" ou "compacto" (pergunta | resposta); modelo=coletum_fotografico para "relatório fotográfico" ou "só as fotos". Se o pedido tem um ajuste que nenhum dos três faz (ver ajustes), a ferramenta recusa e diz quais ajustes não existem, sem gerar outro visual: avise o cliente e ofereça o modelo dele (analisar_pdf_modelo e gerar_pdf_modelo).
Escolha: (1) preenchimentos com id e criado_em (de buscar_preenchimentos); (2) ids_preenchimentos com um período; (3) só filtros, até max_preenchimentos. Na escolha (3) entram os mais recentes, porque a API devolve do mais recente para o mais antigo: "PDF dos 5 últimos" = sem filtro e max_preenchimentos=5 (1 chamada); para mostrar a lista antes, buscar_preenchimentos com pagina=1 e tamanho_pagina=5 e passe id e criado_em. Por padrão sai um PDF com todos, cada preenchimento em página nova; modo=um_por_preenchimento gera um arquivo para cada. As fotos são baixadas pelo link direto do armazenamento, sem passar pela conversa; se o link não responde, entra um quadro "foto indisponível". Custo: 1 chamada por janela de busca (ids com datas próximas dividem a mesma janela) ou 1 por página de filtro, mais 1 pela estrutura na primeira vez. Baixar fotos não gasta cota, mas gera tráfego para o Coletum (até 200 fotos por chamada). Devolve só caminhos, links, páginas e contagens, nunca o conteúdo (vários arquivos: o link de cada um e o da pasta). Ao terminar, sempre mostre ao usuário o caminho completo de cada arquivo (vem no começo da resposta e em mostrar_ao_usuario), em bloco de código, para ele copiar; se ele pedir para abrir, use mostrar_arquivo. Nunca diga só 'na pasta do projeto'.
Inputs: id_formulario (required), modo, modelo, origem, +9 more.
Lê as preferências do cliente salvas (quem lê os documentos, para quê, frequência, identidade visual, o que nunca aparece, formato preferido). Leia no começo de qualquer tarefa de documento para não perguntar de novo. Não chama a API.
Inputs: no named parameters.
Lista os formulários da conta: id, nome, status, categoria e versão.
Custo: 1 chamada por página, cerca de 200 bytes por formulário. Use tamanho_pagina alto (até 500) para ver tudo em 1 chamada. É o ponto de partida: o id daqui entra em todas as outras ferramentas.
Inputs: nome, pagina, status, tamanho_pagina.
Lista os modelos de PDF disponíveis: os salvos na pasta de modelos do cliente e os embutidos (somente leitura: coletum_exportacao, que replica o PDF da exportação do Coletum, e os alternativos coletum_colunas e coletum_fotografico, com aparencia_aceita). Diz também se há preferências salvas. Com mostrar_template, traz o texto de um modelo para ajustar e salvar com outro nome. Não chama a API.
Inputs: mostrar_template.
Abre a pasta do sistema com o arquivo selecionado (Finder no Mac, Explorer no Windows; no Linux abre a pasta), para o usuário achar o que o conector gerou. Use quando ele pedir para abrir o arquivo ou a pasta. Só abre o que está na pasta de saída do conector ou o que alguma ferramenta gerou nesta conversa. Não chama a API.
Inputs: caminho (required).
Salva um modelo de PDF na máquina do cliente, para reusar só pelo nome em gerar_pdf_modelo.
Grava // com modelo.typ, modelo.json (descrição, formulários, mapeamento, datas), arquivos/ e fontes/. Não sobrescreve sem substituir=true. Modelos embutidos não podem ser trocados. Não chama a API.
Inputs: nome (required), template_typst (required), logo, fontes, +7 more.
Salva as preferências do cliente em preferencias.md, na pasta de modelos, para as próximas conversas. Não chama a API.
Inputs: texto (required), modo.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 13 tools
Most tools target distinct resources and actions (list forms, get structure, count/search/export submissions, manage templates). The two PDF generators (gerar_pdf_preenchimento vs gerar_pdf_modelo) share the same action (generate PDF) and could be confused, but descriptions clarify that one uses built-in Coletum models and the other uses custom Typst templates.
Almost all names follow a clear verb_noun pattern in Portuguese (listar_formularios, buscar_preenchimentos, gerar_pdf_modelo, etc.). One outlier 'estrutura_formulario' is noun_noun, breaking the pattern slightly, but the set remains highly readable and predictable.
13 tools is well within the ideal 3-15 range and each tool earns its place: form listing, structure retrieval, submission counting/search/export, two PDF generation paths, model analysis/saving, and preference management. No redundant or trivial tools.
The surface covers the core workflows: listing forms, getting structure, counting/searching/exporting submissions, generating PDFs via built-in or custom templates, analyzing/saving templates, and managing preferences. A minor gap is the lack of a tool to fetch full submission details (including group items and attachment links) directly in-conversation, as that requires exporting to disk.
Give AI agents access to form submissions — read, search, update, and process file attachments.
File tools for your AI chat: PDF tables to Excel, merge PDFs, images to PDF, fill PDF forms.
Build, edit and publish forms and read their responses from your AI assistant.
Jotform MCP server for ChatGPT, Claude and any AI agent: list forms, read submissions, edit submission, archive submissions, set notification recipients and create report in your own Jotform account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Jotform yourself; Cotlet does not store your password and you need no Jotform API key. About the official Jotform API: Jotform has a full REST API with API keys, and an official hosted MCP server with only 5 tools (checked 17 Oct 2026). The MCP covers listing and creating forms, editing forms, creating a submission and reading submissions. Setup and FAQ: https://cotlet.dev/integrations/jotform-api-mcp-server
