kobotoolbox-mcp-server
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., "@kobotoolbox-mcp-server Analyse les réponses du formulaire et génère un rapport Word et Excel."
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.
kobotoolbox-mcp-server
Serveur MCP pour KoboToolbox : crée des formulaires, analyse les données collectées selon un objectif donné, et produit des livrables finis — classeur Excel analytique avec graphiques natifs, rapport Word, PDF — le tout piloté depuis une conversation Claude.
Ce que ça permet concrètement
« Analyse mon formulaire de suivi des parcelles pour identifier les régions à appuyer en priorité, et fais-moi un rapport Word et un Excel. »
Claude charge les données, les nettoie, calcule les statistiques et les croisements, rédige l'analyse, et écrit les fichiers sur ton disque.
Related MCP server: Talk2Data InsightGenius
Outils disponibles
Analyse et rapports
Outil | Description |
| Charge toutes les soumissions, les nettoie (codes → libellés, groupes aplatis, types convertis) et renvoie la liste des questions analysables + un rapport qualité |
| Statistiques descriptives par question (fréquences, moyenne, médiane, écart-type, quartiles…) |
| Tableau croisé entre deux questions (effectifs, % ligne/colonne, moyenne ou somme d'une variable numérique) |
| Lit les lignes nettoyées (utile pour les réponses en texte libre) |
| Génère les livrables : .xlsx analytique, .docx, .pdf |
Gestion des formulaires
Outil | Description |
| Liste tes formulaires |
| Détail d'un formulaire : arborescence des sections, sauts conditionnels, contraintes, langues |
| Crée un formulaire (XLSForm complet) et le déploie |
| Modification ciblée : renommer un libellé, ajouter un choix, poser un saut conditionnel — sans renvoyer tout le questionnaire |
| Remplace l'intégralité des questions (garde-fou si des données existent déjà) |
| Déploie ou redéploie un formulaire |
| Arrête la collecte sans rien supprimer (ou réactive) |
| Duplique un questionnaire pour une nouvelle vague/zone |
| Historique des versions déployées et retour arrière vers l'une d'elles |
| Télécharge le formulaire au format XLSForm |
| Téléverse un XLSForm existant (nouveau formulaire ou écrasement) |
| Suppression définitive (exige |
Diffusion et partage
Outil | Description |
| Les liens de collecte (hors ligne, en ligne, usage unique, aperçu, iframe), un QR code imprimable, et si le formulaire est réellement public |
| Active/révoque les soumissions anonymes (= rendre le lien public), et gère les collaborateurs ( |
Données collectées
Outil | Description |
| Liste brute d'une page de soumissions |
| Détail d'une soumission |
| Marque des réponses approuvées / rejetées / en attente (non destructif) |
| Supprime des réponses précises (tests, doublons, retrait demandé) |
| Récupère les photos, audios et fichiers joints aux réponses |
| Envoie une réponse par API (tester un formulaire, migrer des données papier) |
| Export Excel/CSV brut généré par Kobo |
Diagnostic
Outil | Description |
| Vérifie la connexion, le token, l'environnement Python et le dossier de sortie |
Construire un bon questionnaire
kobo_create_form expose l'essentiel de XLSForm. La liste de questions est plate : l'imbrication passe par des lignes begin_group / end_group et begin_repeat / end_repeat, qui doivent être équilibrées.
Colonne | À quoi ça sert |
| Saut conditionnel — la question n'apparaît que si l'expression est vraie : |
| Validation de la réponse : |
| Sections ; avec |
| Données répétées (une ligne par plat, par parcelle…) |
| Valeur calculée (type |
|
|
|
|
| Partager une même liste de choix entre plusieurs questions |
types | Métadonnées d'entretien (durée réelle, appareil) |
⚠️ Le type téléphone s'écrit phonenumber, pas phone_number : cette seconde orthographe fait répondre au serveur Kobo une erreur HTTP 500 sans message. Le serveur corrige l'alias automatiquement et valide toute la liste avant d'appeler Kobo — types inconnus, noms en double, groupes non fermés et listes de choix manquantes sont signalés d'un coup, avec le numéro de la question fautive.
Déployé ≠ public
Un formulaire déployé possède un lien Enketo, mais celui-ci exige une connexion Kobo tant que les soumissions anonymes ne sont pas activées :
kobo_set_sharing uid=<...> anonymous_submissions=trueLe public peut alors répondre, jamais lire les réponses déjà collectées. kobo_get_collect_links avec include_qr=true renvoie en prime le QR code à imprimer.
Ce que contient le classeur Excel généré
Synthèse — objectif, résumé exécutif, constats, recommandations, limites des données
Une feuille par section d'analyse — tableaux + graphiques Excel natifs et éditables (pas des images)
Tableaux croisés — croisements calculés avec totaux
Données nettoyées — toutes les réponses, libellées, sous forme de Tableau Excel nommé
DonneesKoboQualité des données — complétude question par question
À propos des TCD
Les croisements sont livrés sous forme de tableaux calculés, pas d'objets TableauCroiséDynamique vivants : aucune librairie open source (JS comme Python) ne sait en créer. C'est précisément pourquoi les données nettoyées sont formatées en Tableau Excel nommé — clique dedans, puis Insertion → Tableau croisé dynamique, et tu as ton TCD natif en deux clics.
Installation
1. Prérequis
Le serveur tourne sur Linux, macOS et Windows. Il lui faut trois choses :
Linux (Debian/Ubuntu) | macOS | Windows | |
Node.js ≥ 18 |
|
| |
Python 3 |
|
| python.org — coche « Add python.exe to PATH » à l'installation |
LibreOffice (export PDF uniquement) |
|
|
Puis les librairies Python du moteur de rendu :
python3 -m pip install -r requirements.txt # Linux / macOS
py -m pip install -r requirements.txt # Windowsxlsxwriter et matplotlib sont requis ; python-docx ne l'est que pour les sorties Word et PDF. L'outil kobo_doctor te dit exactement ce qui manque.
Deux pièges hors Linux, que le serveur gère seul mais qu'il vaut mieux connaître :
Sur Windows, la commande s'appelle
python, paspython3— ce dernier nom y est réservé à un raccourci qui ouvre le Microsoft Store. Le serveur choisit doncpythonpar défaut sur Windows etpython3ailleurs ;PYTHON_BINn'est à renseigner que si ton interpréteur est ailleurs (Anaconda, venv).Sur macOS et Windows, l'installeur LibreOffice ne met rien dans le
PATH. Le serveur va donc le chercher à son emplacement standard (/Applications/LibreOffice.app/…,C:\Program Files\LibreOffice\…). S'il est installé ailleurs, renseigneSOFFICE_BIN.
2. Récupérer ton token API Kobo
Connecte-toi sur https://kf.kobotoolbox.org (ou ton serveur Kobo)
Paramètres du compte → Sécurité → clé API
Copie le token
3. Configurer
npm install
npm run build
cp .env.example .env # puis renseigne KOBO_API_TOKENSous Windows,
cpexiste dans PowerShell ; dans l'invite de commandes classique, écriscopy .env.example .env.
Variables du .env :
Variable | Rôle |
| Requis. Ton token API Kobo |
|
|
| Dossier où sont écrits les rapports. Par défaut |
| Interpréteur Python qui possède les librairies. Par défaut |
| Binaire LibreOffice pour l'export PDF. Détecté automatiquement ; à renseigner seulement s'il est installé hors des emplacements standards |
| Uniquement pour le transport HTTP |
| Hôte KoboCAT pour l'envoi de données. Déduit automatiquement ; à renseigner sur une instance auto-hébergée |
| Nombre de tentatives sur throttling/erreur serveur (défaut |
| Délai initial du backoff exponentiel (défaut |
4. Brancher à Claude Code
# Linux / macOS
claude mcp add kobotoolbox --scope user -- node /chemin/absolu/vers/kobotoolbox-mcp-server/dist/index.js
# Windows (PowerShell) — chemin absolu lui aussi, avec la lettre de lecteur
claude mcp add kobotoolbox --scope user -- node C:\Users\moi\kobotoolbox-mcp-server\dist\index.jsLe chemin doit être absolu : --scope user enregistre le serveur pour tout le compte, donc Claude Code peut ensuite être lancé depuis n'importe quel dossier — sans jamais revenir dans celui du projet. Le serveur lit son .env à côté de son propre code, pas dans le répertoire courant.
Vérifie avec claude mcp list. Après toute modification du code : npm run build, puis relance Claude Code.
Utilisation
Une session d'analyse typique :
« Liste mes formulaires Kobo »
« Charge les données du formulaire X » → Claude voit les questions et la qualité des données
« Quelles régions ont le plus de parcelles en mauvais état ? » → croisements
« Fais-moi un rapport Word et Excel sur l'état sanitaire par région, avec des recommandations »
Les fichiers atterrissent dans KOBO_OUTPUT_DIR et Claude t'en donne le chemin complet.
Filtrer les données : la plupart des outils acceptent un query au format Mongo, par exemple {"region":"so"} ou {"_submission_time":{"$gte":"2026-01-01"}}.
Architecture
Le serveur ne « devine » pas l'analyse : Claude rédige le contenu (objectif, commentaires, constats, recommandations) et déclare quelles tables et quels graphiques produire ; le serveur calcule tous les chiffres depuis les soumissions réelles. Les nombres du rapport ne peuvent donc pas diverger des données.
kobotoolbox-mcp-server/
├── src/
│ ├── index.ts # point d'entrée (stdio par défaut, HTTP en option)
│ ├── constants.ts # configuration (.env résolu depuis la racine du projet)
│ ├── services/
│ │ ├── koboClient.ts # client API Kobo (retry, erreurs lisibles, pagination)
│ │ ├── formBuilder.ts # génération et validation XLSForm
│ │ ├── codebook.ts # structure du formulaire : libellés, choix, groupes
│ │ ├── dataset.ts # nettoyage, libellisation, rapport qualité
│ │ ├── analyze.ts # statistiques descriptives et tableaux croisés
│ │ ├── store.ts # cache des données (15 min) partagé entre outils
│ │ ├── reportBuilder.ts # directives du modèle -> spécification de rapport
│ │ └── renderer.ts # appel du moteur Python
│ ├── tools/ # définitions des outils MCP
│ └── schemas/ # validation Zod des entrées
├── scripts/
│ └── render_report.py # génération xlsx / docx / pdf
├── tests/ # tests unitaires (vitest)
├── requirements.txt # dépendances Python du moteur de rendu
└── out/ # livrables générés (git-ignoré)Développement
npm run build # compile TypeScript -> dist/
npm run typecheck # vérification des types sans émission
npm test # tests unitaires (vitest)
npm run test:watchNotes de sécurité
Le token API Kobo donne accès à tous tes formulaires et données. Il vit dans
.env, qui est git-ignoré — ne le committe jamais.kobo_delete_formest irréversible : il exigeconfirm: trueet, si le formulaire contient des données, le nombre exact de soumissions. Pour simplement arrêter une collecte, utilisekobo_archive_form.kobo_set_sharingavecanonymous_submissions=truerend le formulaire remplissable par quiconque possède le lien. Confirme-le avec l'utilisateur avant de l'activer.Le serveur ne conserve rien sur disque hormis les rapports que tu demandes ; les données en mémoire expirent après 15 minutes.
Partager ce serveur
Je l'ai conçu pour tourner en local, une instance par personne. Le token Kobo est lu une seule fois au démarrage (KOBO_API_TOKEN dans .env) et vaut pour tout le serveur : il n'y a pas de token par utilisateur ni par requête. Chacun installe donc sa propre copie avec son propre token, et ne voit que ses propres formulaires.
⚠️ Ne copie jamais le dossier tel quel (cp -r, clé USB, Drive, Slack) : il contient .env, donc mon token, donc l'accès à l'ensemble de mes données Kobo.
Par dépôt git — ce que je recommande
git pushLe dépôt est publié ici : https://github.com/OuattaraTech/kobotoolbox-mcp-server. Un collaborateur n'a plus qu'à le cloner.
Le .gitignore exclut .env, node_modules/, dist/ et out/ : ni le token ni les rapports déjà générés ne partent avec le code.
Par archive, sans passer par GitHub
tar --exclude=node_modules --exclude=dist --exclude=.env --exclude=out --exclude=.git \
-czf ~/kobo-mcp.tar.gz -C ~/Documents kobotoolbox-mcp-server(tar est présent d'origine sur Windows 10+ ; il suffit d'y adapter les chemins.)
Ce que la personne fait de son côté
Elle suit Installation, avec son token Kobo :
git clone https://github.com/OuattaraTech/kobotoolbox-mcp-server.git && cd kobotoolbox-mcp-server
npm install && npm run build
python3 -m pip install -r requirements.txt # "py -m pip" sous Windows
cp .env.example .env # puis y mettre son propre KOBO_API_TOKEN
claude mcp add kobotoolbox --scope user -- node /chemin/absolu/vers/dist/index.jsÇa marche sur les trois systèmes ; les seules différences (nom de l'interpréteur Python, installation de LibreOffice, forme du chemin absolu) sont détaillées dans les Prérequis.
Premier test à lui indiquer : demander à Claude de lancer kobo_doctor, qui vérifie d'un coup la connexion, le token, les librairies Python et le dossier de sortie.
Par npm
Le package.json est déjà prêt pour la publication (bin, files, prepublishOnly), et l'installation tiendrait alors en une commande, sans clone ni build :
claude mcp add kobotoolbox --scope user --env KOBO_API_TOKEN=xxx -- npx -y @ouattaratech/kobotoolbox-mcp-serverDeux choses à régler avant de publier : le nom kobotoolbox-mcp-server est déjà pris sur npm par un autre projet, il faut donc un nom scopé (@ouattaratech/kobotoolbox-mcp-server) ; et repository.url pointe vers un dépôt qui n'existe pas encore.
Une seule instance pour toute une équipe
C'est le transport HTTP ci-dessous, mais je ne le conseille que sur un réseau interne de confiance, pour trois raisons :
Compte Kobo unique — tout le monde agit avec mon token, sur mes formulaires. Ça ne convient qu'à une équipe qui travaille déjà sur le même compte Kobo.
Les rapports restent sur le serveur — ils sont écrits dans le
KOBO_OUTPUT_DIRde la machine hôte, et il n'existe pas d'endpoint de téléchargement pour les récupérer.MCP_ACCESS_KEYest une clé unique partagée, pas une authentification par utilisateur — et sans reverse proxy HTTPS devant, elle circule en clair.
Transport HTTP (optionnel)
Pour partager le serveur sur le réseau plutôt que de l'exécuter en local :
# Linux / macOS
TRANSPORT=http PORT=3000 MCP_ACCESS_KEY=$(openssl rand -hex 32) npm start# Windows (PowerShell) — openssl n'y est pas livré d'office
$env:TRANSPORT="http"; $env:PORT="3000"
$env:MCP_ACCESS_KEY=-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) })
npm startL'endpoint est alors http://<hôte>:3000/mcp, protégé par Authorization: Bearer <MCP_ACCESS_KEY>. Dans ce mode, les rapports sont écrits sur le serveur, pas sur la machine du client — il faudrait ajouter un endpoint de téléchargement pour les récupérer.
Available Tools
27 toolskobo_analyzeDescriptive Statistics of KoboToolbox DataARead-onlyIdempotent
Compute descriptive statistics for every question (or a chosen subset) of a form.
For each question it returns the statistics that fit its type:
categorical: counts and percentages per answer option (multi-select handled correctly — percentages are of respondents, so they can exceed 100%)
numeric: n, mean, median, standard deviation, min, max, quartiles, sum
date: earliest and latest
free text: number of distinct answers plus examples
Args:
uid (string): the form's asset uid
columns (array, optional): restrict to these questions (field name or question label)
query (string, optional): Mongo-style filter
response_format ('markdown' | 'json')
Loads the data automatically if it isn't cached yet.
Examples:
Use when: "What do the responses to my cocoa form look like?" -> uid=...
Use when: "What's the average plot size?" -> columns=["plot_size"]
Don't use when: you need two questions crossed (use kobo_crosstab)
Inputs: uid (required), query, columns, response_format.
kobo_archive_formArchive or Reactivate a KoboToolbox FormAIdempotent
Stop a form from accepting new submissions without deleting anything, or bring an archived form back.
This is the correct way to end a data collection round: every response is kept and stays exportable. Use it instead of kobo_delete_form, which destroys the data.
Args:
uid (string): asset uid of the deployed form
active (boolean): false to archive, true to reactivate
Returns: the resulting deployment status.
Inputs: uid (required), active (required).
kobo_build_reportGenerate Excel / Word / PDF Analysis ReportA
Produce finished deliverables from a form's data: an analytical Excel workbook, a written Word report, and/or a PDF — saved to disk.
YOU write the analysis (objective, summary, findings, section commentary, recommendations); the server computes every figure from the real submissions, so the numbers in the deliverable always match the data. Never type counts or percentages into 'custom' tables that the server can compute for you — use the directives below instead.
Each section carries your prose plus 'visuals', declared as directives:
{source:"frequencies", column:"crop_health", chart_kind:"pie"} — counts/% per answer, as table and chart
{source:"numeric_summary", column:"plot_size"} — mean/median/std/quartiles table
{source:"crosstab", row_column:"region", col_column:"crop_health", metric:"count"} — contingency table + grouped chart
{source:"custom", columns:[...], rows:[[...]]} — only for figures the server cannot derive Each accepts: show ('table'|'chart'|'both'), chart_kind, title, note (a "how to read this" caption), top_n.
What the Excel workbook contains: a summary sheet (objective, executive summary, findings, recommendations), one sheet per section with tables and NATIVE, editable Excel charts, a cross-tab sheet, the cleaned data as a real Excel Table named 'DonneesKobo' (select it, then Insert > PivotTable to build your own pivot in two clicks), and a data-quality sheet.
Note on pivot tables: cross-tabs are delivered as computed tables, not as live PivotTable objects — no open-source library can create those. The named Excel Table above is there precisely so you can add one yourself instantly.
Args:
uid (string): the form's asset uid
objective (string): the analytical question this report answers
formats (array): any of 'xlsx', 'docx', 'pdf'
title, methodology, summary, findings[], recommendations[]: your written content
sections[]: {heading, text, visuals[]}
file_name (string, optional): base name without extension
query (string, optional): Mongo-style filter restricting the analysis
Returns: the full path of each generated file.
Run kobo_load_data first so you know which questions exist and what shape the data is in.
Inputs: uid (required), sections (required), objective (required), query, +8 more.
kobo_clone_formClone a KoboToolbox FormA
Copy an existing form's structure into a brand-new project, without its submissions.
Useful to reuse a questionnaire for a new round, region or season, or to experiment on a copy instead of a live form.
Args:
uid (string): asset uid of the form to copy
name (string, optional): name for the copy (default ' (copie)')
deploy (boolean, default false): deploy the copy immediately
Returns: the new form's uid and status.
Inputs: uid (required), name, deploy.
kobo_create_formCreate KoboToolbox FormA
Create a new form (survey) from a list of questions, and optionally deploy it immediately so it can start collecting submissions.
The question list is FLAT: sections and repeats are expressed with begin_group/end_group and begin_repeat/end_repeat rows, which must be balanced.
Args:
name (string): form/project title
description (string, optional): short description
questions (array): ordered list of questions. Each has:
type: see the type enum. Use 'phonenumber' (NOT 'phone_number') for a phone field.
name: internal field name, unique across the whole form
label: question text (string, or {language: text} for a multilingual form)
required, hint, choices, relevant, constraint, constraint_message, calculation, default, appearance, read_only, parameters
deploy (boolean, default true): deploy immediately vs. leave as draft
Returns: the new form's uid, deployment status, and — once deployed — the public collect links.
Examples:
Sections and skip logic: questions=[ {type:"begin_group",name:"identification",label:"Identification",appearance:"field-list"}, {type:"text",name:"nom",label:"Nom de l'établissement",required:true}, {type:"select_one",name:"categorie",label:"Catégorie",choices:[{name:"maquis",label:"Maquis"},{name:"autre",label:"Autre"}]}, {type:"text",name:"categorie_autre",label:"Précisez",relevant:"${categorie} = 'autre'"}, {type:"integer",name:"annee",label:"Année",constraint:". >= 1950 and . <= 2030",constraint_message:"Année invalide"}, {type:"end_group",name:"identification"} ]
Repeating data: begin_repeat "plats" ... end_repeat, one row per dish.
Don't use when: you want to change an existing form (use kobo_patch_form for a targeted edit, kobo_update_form to replace everything)
Error Handling:
The question list is validated locally first: unknown types, duplicate names, unbalanced groups, selects without choices and bad choice codes are reported precisely, before any request reaches Kobo.
Inputs: name (required), questions (required), deploy, description.
kobo_crosstabCross-tabulate Two KoboToolbox QuestionsARead-onlyIdempotent
Cross two questions to see how answers to one vary with the other — the core of comparative analysis.
Args:
uid (string): the form's asset uid
row_column (string): question forming the rows (field name or label)
col_column (string): question forming the columns
metric: 'count' (default), 'row_pct', 'col_pct', 'mean' or 'sum'
value_column (string): numeric question to average/sum — required for 'mean' and 'sum'
query (string, optional): Mongo-style filter
response_format ('markdown' | 'json')
Returns: the contingency table with row, column and grand totals, and how many submissions were excluded for missing either answer.
Examples:
Use when: "Is crop health worse in some regions?" -> row_column="region", col_column="crop_health"
Use when: "Share of each health status within each region" -> ..., metric="row_pct"
Use when: "Average plot size by region and crop" -> row_column="region", col_column="crop", metric="mean", value_column="plot_size"
Inputs: uid (required), col_column (required), row_column (required), query, +3 more.
kobo_delete_formDelete KoboToolbox FormADestructiveIdempotent
Permanently delete a form AND ALL ITS SUBMISSIONS. THIS CANNOT BE UNDONE.
Args:
uid (string): asset uid of the form to delete
confirm (true): must be explicitly set to true
confirm_submission_count (number): required when the form has submissions — pass the exact count, to prove the data loss is intended
Don't use when: you just want to stop collecting data. Use kobo_archive_form instead — it keeps every response.
Inputs: uid (required), confirm (required), confirm_submission_count.
kobo_delete_submissionsDelete KoboToolbox SubmissionsADestructiveIdempotent
Permanently delete specific submissions from a form. THIS CANNOT BE UNDONE.
Use it to remove test entries, duplicates, or a response a respondent asked to withdraw.
Args:
uid (string): asset uid of the form
submission_ids (array of strings): the "_id" values from kobo_list_submissions
confirm (true): must be explicitly set to true
Don't use when: you want to discard a whole form's data — that is kobo_delete_form. To merely flag bad rows while keeping them, use kobo_validate_submissions with 'not approved' instead.
Inputs: uid (required), confirm (required), submission_ids (required).
kobo_deploy_formDeploy KoboToolbox FormAIdempotent
Deploy a draft form (or redeploy a changed one) so it becomes active and can collect submissions.
Args:
uid (string): asset uid of the form to deploy
Returns: the new deployment status and the collect links.
Note: deploying makes the form live but NOT public — the Enketo link still asks for a Kobo login until anonymous submissions are enabled with kobo_set_sharing.
Inputs: uid (required).
kobo_doctorCheck the KoboToolbox MCP Server SetupARead-onlyIdempotent
Diagnose this server's configuration: the Kobo connection, the API token, the output directory and the Python report renderer.
Run it first when a tool fails for an unclear reason, or right after installing the server.
Returns: a pass/fail line per check, with the exact command to fix anything broken.
Inputs: response_format.
kobo_download_attachmentsDownload KoboToolbox AttachmentsARead-onlyIdempotent
Download the photos, audio, video and files attached to submissions.
A form with an 'image' question (a shopfront photo, a signed consent form, a damaged crop) stores its files on Kobo, and nothing in an Excel export contains them — only file names. This fetches the actual files to disk, organised one folder per submission.
Args:
uid (string): asset uid of the form
submission_ids (array, optional): limit to these submissions; omit for all
output_dir (string, optional): where to write (default: /_attachments)
max_files (number, default 200): safety cap
Returns: the directory written, the number of files and their total size.
Inputs: uid (required), max_files, output_dir, submission_ids.
kobo_export_submissions_excelExport KoboToolbox Submissions to ExcelARead-only
Generate a downloadable Excel (.xlsx) or CSV export of all submissions for a form, and return the file itself (base64-encoded) plus a direct download link.
This triggers a fresh export on the Kobo server, waits (up to ~90s) for it to finish, downloads the result, and returns it as an embedded file the calling app can save to disk.
Args:
uid (string): the form's asset uid (from kobo_list_forms)
format ('xlsx' | 'csv', default 'xlsx')
language (string, optional): label language for the column headers on a multilingual form
Returns: the file as an embedded resource (base64), its size, and a direct download URL as a fallback.
Examples:
Use when: "Give me an Excel file of all responses to my cocoa form" -> uid=..., format="xlsx"
Don't use when: you just want to read a few submissions in chat (use kobo_list_submissions instead — much faster)
Error Handling:
Returns "Error: ... did not complete within 90s" for very large forms — the export may still finish server-side; check the Kobo web UI's export history
Inputs: uid (required), format, language.
kobo_export_xlsformDownload a Form as XLSFormARead-onlyIdempotent
Download a form as a real XLSForm .xlsx workbook — the standard exchange format for ODK/Kobo questionnaires.
Use it to hand the questionnaire to someone else, keep it under version control, edit it in Excel, or re-import it elsewhere with kobo_import_xlsform.
Args:
uid (string): asset uid of the form
output_path (string, optional): where to write the file
Returns: the path written and its size.
Inputs: uid (required), output_path.
kobo_form_versionsKoboToolbox Form Version HistoryADestructiveIdempotent
List a form's deployed versions, and roll back to one of them.
Kobo keeps every version that was ever deployed. This is the way back when a change breaks a live form: redeploying a past version restores the old structure without touching the submissions already collected.
Args:
uid (string): asset uid of the form
rollback_to (string, optional): version uid to redeploy. Omit to only list the history.
limit (number, default 30): how many versions to list
response_format ('markdown' | 'json')
Returns: the version history (newest first) with deployment dates, and the resulting status after a rollback.
Notes:
Rolling back changes the form structure only. Answers collected under the newer version stay in the database, but fields that no longer exist drop out of exports.
Inputs: uid (required), limit, rollback_to, response_format.
kobo_get_collect_linksGet KoboToolbox Collect LinksARead-onlyIdempotent
Get the shareable links of a deployed form — the actual deliverable once a form is built.
Returns every Enketo URL Kobo publishes:
offline: caches in the browser and works without a connection, syncing later. The one to give field teams.
online: plain web form
single: submits once and closes, for one-response-per-person links
preview: renders the form without saving anything, for internal review
iframe: to embed the form in a web page
It also reports whether the form is genuinely PUBLIC. A deployed form's link still asks for a Kobo login until anonymous submissions are enabled — use kobo_set_sharing for that.
Args:
uid (string): asset uid of the deployed form
include_qr (boolean, default false): also return a QR code image of the offline link, to print on a flyer, a poster or a table card
response_format ('markdown' | 'json')
Inputs: uid (required), include_qr, response_format.
kobo_get_data_sampleRead Cleaned KoboToolbox RowsARead-onlyIdempotent
Return actual cleaned rows of the dataset, with labels rather than codes.
Use this to read open-ended answers, sanity-check the data before drawing conclusions, or inspect specific records. For aggregate figures prefer kobo_analyze or kobo_crosstab — they are far more compact.
Args:
uid (string): the form's asset uid
limit (number): rows to return, 1-200 (default 20)
offset (number): rows to skip (default 0)
columns (array, optional): only these questions
query (string, optional): Mongo-style filter
response_format ('markdown' | 'json')
Inputs: uid (required), limit, query, offset, +2 more.
kobo_get_formGet KoboToolbox Form DetailsARead-onlyIdempotent
Get full details of a single form: its question structure, section nesting, skip logic and validation rules.
Args:
uid (string): the form's asset uid (from kobo_list_forms)
language (string, optional): which language's labels to show on a multilingual form (e.g. 'fr')
response_format ('markdown' | 'json')
Returns: name, deployment status, submission count, available languages, and the question outline — groups and repeats shown as indented sections, with required, skip logic and constraints annotated.
Error Handling:
Returns "Error: ... not found" if the uid doesn't exist or isn't accessible with this token
Inputs: uid (required), language, response_format.
kobo_get_submissionGet a Single KoboToolbox SubmissionARead-onlyIdempotent
Get the full detail of one submission by its id.
Args:
uid (string): the form's asset uid
submission_id (string): the submission id (the "_id" field from kobo_list_submissions)
response_format ('markdown' | 'json')
Returns: every field and value recorded in that submission.
Inputs: uid (required), submission_id (required), response_format.
kobo_import_xlsformImport an XLSFormADestructive
Upload an XLSForm .xlsx workbook to Kobo, either as a new form or to overwrite an existing one.
Use it when a questionnaire already exists as a spreadsheet, or to round-trip a form edited in Excel.
Args:
file_path (string): path to the .xlsx on disk
name (string, optional): name for the imported form
uid (string, optional): asset uid to overwrite; omit to create a new form
deploy (boolean, default false): deploy once the import finishes
Returns: the resulting form uid and import status.
Error Handling:
Kobo validates the workbook server-side; a malformed XLSForm comes back with the specific row/column it rejected.
Inputs: file_path (required), uid, name, deploy.
kobo_list_formsList KoboToolbox FormsARead-onlyIdempotent
List forms/projects (surveys) accessible with the configured API token.
Does NOT return submission data — use kobo_list_submissions for that.
Args:
search (string, optional): filter forms whose name contains this text
limit (number): max forms to return, 1-100 (default 30)
offset (number): pagination offset (default 0)
response_format ('markdown' | 'json')
Returns: form uid, name, deployment status, and submission count for each form.
Examples:
Use when: "What forms do I have on Kobo?" -> no params
Use when: "Find my cocoa tracking form" -> search="cocoa"
Inputs: limit, offset, search, response_format.
kobo_list_submissionsList KoboToolbox Form SubmissionsARead-onlyIdempotent
List submitted responses for a form, most recent first.
Args:
uid (string): the form's asset uid (from kobo_list_forms)
limit (number): max submissions to return, 1-100 (default 30)
offset (number): pagination offset (default 0)
query (string, optional): Mongo-style JSON filter, e.g. '{"crop_health":"poor"}'
response_format ('markdown' | 'json')
Returns: submission id, submission time, and answered fields for each submission.
Examples:
Use when: "Show me the latest 10 responses to my cocoa form" -> uid=..., limit=10
Use when: "Which submissions reported poor crop health?" -> query='{"crop_health":"poor"}'
Don't use when: you want a downloadable Excel file (use kobo_export_submissions_excel instead)
Inputs: uid (required), limit, query, offset, +1 more.
kobo_load_dataLoad and Clean KoboToolbox DataARead-onlyIdempotent
Download ALL submissions of a form and prepare them for analysis. Start every analysis here.
Unlike kobo_list_submissions (one page of raw records), this pulls the whole dataset, replaces stored choice codes with their labels, converts numbers and dates, flattens groups, and reports data quality. The cleaned snapshot is cached for 15 minutes and reused by kobo_analyze, kobo_crosstab, kobo_get_data_sample and kobo_build_report.
Args:
uid (string): the form's asset uid
query (string, optional): Mongo-style server-side filter, e.g. '{"region":"Sud-Ouest"}'
max_rows (number): safety cap (default: everything, up to 50000)
language (string, optional): label language for multilingual forms
refresh (boolean): re-download instead of using the cache
response_format ('markdown' | 'json')
Returns: the list of analysable questions with their measurement type (categorical / numeric / datetime / text) and answer options, the number of submissions, and a data-quality summary (missing values, duplicates, skipped repeat groups).
Use the returned question list to decide what to analyse — its "field" values are what you pass to the other tools.
Inputs: uid (required), query, refresh, language, +2 more.
kobo_patch_formPatch KoboToolbox FormADestructiveIdempotent
Make targeted changes to an existing form without resending the whole question list.
This is the safe way to fix a typo, add a choice, or attach skip logic to a form that is already collecting data — everything not named is left exactly as it is.
Args (all optional, combine freely):
uid (string): the form to patch
set_label: [{name, label}] — relabel existing questions
set_hint: [{name, hint}]
set_required: [{name, required}]
set_relevant: [{name, relevant}] — set skip logic; empty string clears it
set_constraint: [{name, constraint, constraint_message}] — empty constraint clears it
add_choices: [{name, choices:[{name,label}]}] — append options to a select question
remove_questions: [names] — delete questions; removing a group removes its contents
redeploy (boolean, default true)
Returns: a per-change report of what was applied and what could not be found.
Examples:
Fix one label: set_label=[{name:"nom_etablissement", label:"Nom de l'établissement"}]
Add skip logic after the fact: set_relevant=[{name:"type_autre", relevant:"${type} = 'autre'"}]
Add a payment option: add_choices=[{name:"moyens_paiement", choices:[{name:"wave",label:"Wave"}]}]
Inputs: uid (required), redeploy, set_hint, set_label, +5 more.
kobo_set_sharingSet KoboToolbox Form SharingADestructiveIdempotent
Control who can fill in a form and who can work on it.
Two independent things:
anonymous_submissions: makes the collect link usable by ANYONE who has it, with no Kobo account. This is what turns a deployed form into a genuinely public link. It never lets the public read the responses already collected — only submit new ones.
share_with / revoke_from: give or remove named collaborators' access to the form and its data.
Roles:
view: see the form and read its submissions
edit: also add and change submissions, and edit the form
manage: full control, including sharing it further
Args:
uid (string): asset uid of the form
anonymous_submissions (boolean, optional): true to publish, false to revoke
share_with: [{username, role}]
revoke_from: [usernames] — removes every permission that user holds
response_format ('markdown' | 'json')
Returns: the resulting access list, and the collect links when the form becomes public.
Examples:
"Make my form publicly fillable" -> anonymous_submissions=true
"Let Awa edit the data" -> share_with=[{username:"awa", role:"edit"}]
Notes:
Publishing a form is outward-facing: anyone with the URL can then submit. Confirm with the user before enabling it unless they asked.
Inputs: uid (required), share_with, revoke_from, response_format, +1 more.
kobo_submit_dataSubmit Data to a KoboToolbox FormA
Send a response to a deployed form through the API, without going through the web form.
Use it to test a form end-to-end before sending enumerators out, or to migrate answers already collected on paper or in a spreadsheet.
Args:
uid (string): asset uid of the DEPLOYED form
answers (object): values keyed by the question's submission path, exactly as kobo_get_form reports it. A question inside a group is "group_name/question_name". select_multiple values are space-separated codes: "especes mobile_money". Dates are ISO: "2026-09-16". geopoint is "lat lon altitude accuracy".
count (number, default 1): submit the same answers several times, for load-testing only
Returns: the instance id Kobo assigned.
Notes:
Submitted rows are real data and count towards the form's submission total. Delete test rows with kobo_delete_submissions.
Attachments (photos, audio) cannot be sent this way — use the web form for those.
Error Handling:
A rejected submission almost always means a field name that does not exist in the form; check the exact paths with kobo_get_form.
Inputs: uid (required), answers (required), count.
kobo_update_formReplace KoboToolbox Form QuestionsADestructiveIdempotent
Replace the ENTIRE question list of an existing form with a new one.
Prefer kobo_patch_form for targeted edits (relabelling, adding choices, changing skip logic) — it leaves the rest of the form untouched and cannot accidentally drop questions.
Args:
uid (string): asset uid of the form to update
questions (array): FULL replacement list — any question left out is REMOVED from the form
redeploy (boolean, default true): redeploy so the new version goes live
confirm_replace (boolean): must be true when the form already has submissions
Notes:
Existing submissions are preserved, but answers to removed questions become orphaned and stop appearing in exports.
The question list is validated locally before anything is sent to Kobo.
Inputs: uid (required), questions (required), redeploy, confirm_replace.
kobo_validate_submissionsSet Validation Status on SubmissionsAIdempotent
Mark submissions as approved, not approved, or on hold — Kobo's data-cleaning workflow.
This is the non-destructive way to handle suspect responses: the row stays in the database and in exports, carrying its status, instead of being deleted.
Args:
uid (string): asset uid of the form
submission_ids (array of strings): the "_id" values to mark
status: 'validation_status_approved' | 'validation_status_not_approved' | 'validation_status_on_hold'
Returns: how many submissions were updated.
Inputs: uid (required), status (required), submission_ids (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 27 tools
Every tool targets a distinct resource+action, with cross-references clarifying adjacent purposes. kobo_list_submissions, kobo_get_data_sample, and kobo_export_submissions_excel are clearly separated as raw paged, cleaned sample, and file export; kobo_patch_form vs kobo_update_form explicitly explain targeted vs full replacement. No two tools could reasonably be confused.
The overwhelming majority follow kobo_<verb>_<object> (kobo_create_form, kobo_list_submissions, kobo_delete_submissions). Minor deviations exist: kobo_form_versions is a noun phrase, and kobo_analyze, kobo_crosstab, kobo_doctor lack the standard verb+object structure. These are still readable and predictable within the overall convention.
At 27 tools, the server lands in the 'too many' band, especially since it bundles three distinct domains: form design/deployment, submission management, and analysis/reporting. While each tool has a distinct role, the surface is heavy for agent selection and would benefit from splitting into focused form, data, and reporting servers.
The surface covers the full form lifecycle (create/read/update/patch/deploy/archive/clone/import/delete/versions), submission workflows (list/get/submit/validate/delete/attachments/export), and analysis (load/analyze/crosstab/data sample/report). Minor gaps include no way to update a form's name/description after creation and no submission answer editing beyond validation status, but these are generally workable around.
Maintenance
Related MCP Connectors
Build forms, quizzes, and surveys from your AI assistant. Create, edit, publish, and read responses.
Build, edit and publish forms and read their responses from your AI assistant.
Create, edit and publish surveys, then read results from your AI chat.
Create, edit and publish surveys and AI interviews, then read responses and reports.
Related MCP Servers
- -licenseBqualityNot gradedmaintenanceA comprehensive Model Context Protocol server that enables Claude Desktop users to manage Tally forms with 23 powerful tools for creating, editing, and analyzing forms, submissions, questions, webhooks, and conditional logic.231-
- FlicenseNot gradedqualityNot gradedmaintenanceAnalyze survey data (.sav, .csv, .xlsx) through Claude — crosstabs with significance testing, ANOVA, correlation, gap analysis, and publication-ready Excel exports. Upload once, analyze unlimited.-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to create, manage, and analyze Google Forms with all question types, sections, quiz mode, and Google Drive/Sheets integration.11MIT
- AlicenseNot gradedqualityDmaintenanceEnables MCP clients to query and export KoboToolbox field data using natural language, allowing users to ask questions about submissions and export data without manual logins.33 npmMIT