Skip to main content
Glama

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

kobo_load_data

Charge toutes les soumissions, les nettoie (codes → libellés, groupes aplatis, types convertis) et renvoie la liste des questions analysables + un rapport qualité

kobo_analyze

Statistiques descriptives par question (fréquences, moyenne, médiane, écart-type, quartiles…)

kobo_crosstab

Tableau croisé entre deux questions (effectifs, % ligne/colonne, moyenne ou somme d'une variable numérique)

kobo_get_data_sample

Lit les lignes nettoyées (utile pour les réponses en texte libre)

kobo_build_report

Génère les livrables : .xlsx analytique, .docx, .pdf

Gestion des formulaires

Outil

Description

kobo_list_forms

Liste tes formulaires

kobo_get_form

Détail d'un formulaire : arborescence des sections, sauts conditionnels, contraintes, langues

kobo_create_form

Crée un formulaire (XLSForm complet) et le déploie

kobo_patch_form

Modification ciblée : renommer un libellé, ajouter un choix, poser un saut conditionnel — sans renvoyer tout le questionnaire

kobo_update_form

Remplace l'intégralité des questions (garde-fou si des données existent déjà)

kobo_deploy_form

Déploie ou redéploie un formulaire

kobo_archive_form

Arrête la collecte sans rien supprimer (ou réactive)

kobo_clone_form

Duplique un questionnaire pour une nouvelle vague/zone

kobo_form_versions

Historique des versions déployées et retour arrière vers l'une d'elles

kobo_export_xlsform

Télécharge le formulaire au format XLSForm .xlsx

kobo_import_xlsform

Téléverse un XLSForm existant (nouveau formulaire ou écrasement)

kobo_delete_form

Suppression définitive (exige confirm + le nombre exact de soumissions)

Diffusion et partage

Outil

Description

kobo_get_collect_links

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

kobo_set_sharing

Active/révoque les soumissions anonymes (= rendre le lien public), et gère les collaborateurs (view / edit / manage)

Données collectées

Outil

Description

kobo_list_submissions

Liste brute d'une page de soumissions

kobo_get_submission

Détail d'une soumission

kobo_validate_submissions

Marque des réponses approuvées / rejetées / en attente (non destructif)

kobo_delete_submissions

Supprime des réponses précises (tests, doublons, retrait demandé)

kobo_download_attachments

Récupère les photos, audios et fichiers joints aux réponses

kobo_submit_data

Envoie une réponse par API (tester un formulaire, migrer des données papier)

kobo_export_submissions_excel

Export Excel/CSV brut généré par Kobo

Diagnostic

Outil

Description

kobo_doctor

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

relevant

Saut conditionnel — la question n'apparaît que si l'expression est vraie : ${categorie} = 'autre'

constraint + constraint_message

Validation de la réponse : . >= 1950 and . <= 2030

begin_group / end_group

Sections ; avec appearance: "field-list", une section = un écran

begin_repeat / end_repeat

Données répétées (une ligne par plat, par parcelle…)

calculation

Valeur calculée (type calculate)

appearance

minimal (liste déroulante), likert, horizontal, year, multiline…

label multilingue

{"Français (fr)": "Nom", "English (en)": "Name"}

choices_list_name

Partager une même liste de choix entre plusieurs questions

types start / end / today / deviceid

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

Le 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é DonneesKobo

  • Qualité 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

sudo apt install nodejs

brew install node

nodejs.org

Python 3

sudo apt install python3 python3-pip

brew install python

python.org — coche « Add python.exe to PATH » à l'installation

LibreOffice (export PDF uniquement)

sudo apt install libreoffice

brew install --cask libreoffice

libreoffice.org

Puis les librairies Python du moteur de rendu :

python3 -m pip install -r requirements.txt   # Linux / macOS
py -m pip install -r requirements.txt        # Windows

xlsxwriter 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, pas python3 — ce dernier nom y est réservé à un raccourci qui ouvre le Microsoft Store. Le serveur choisit donc python par défaut sur Windows et python3 ailleurs ; PYTHON_BIN n'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, renseigne SOFFICE_BIN.

2. Récupérer ton token API Kobo

  1. Connecte-toi sur https://kf.kobotoolbox.org (ou ton serveur Kobo)

  2. Paramètres du compte → Sécurité → clé API

  3. Copie le token

3. Configurer

npm install
npm run build
cp .env.example .env   # puis renseigne KOBO_API_TOKEN

Sous Windows, cp existe dans PowerShell ; dans l'invite de commandes classique, écris copy .env.example .env.

Variables du .env :

Variable

Rôle

KOBO_API_TOKEN

Requis. Ton token API Kobo

KOBO_BASE_URL

https://kf.kobotoolbox.org (global) ou https://eu.kobotoolbox.org (Europe)

KOBO_OUTPUT_DIR

Dossier où sont écrits les rapports. Par défaut ./out dans le projet

PYTHON_BIN

Interpréteur Python qui possède les librairies. Par défaut python3 (Linux/macOS) ou python (Windows) ; mets le chemin absolu si tu utilises Anaconda ou un venv

SOFFICE_BIN

Binaire LibreOffice pour l'export PDF. Détecté automatiquement ; à renseigner seulement s'il est installé hors des emplacements standards

MCP_ACCESS_KEY

Uniquement pour le transport HTTP

KOBO_KC_URL

Hôte KoboCAT pour l'envoi de données. Déduit automatiquement ; à renseigner sur une instance auto-hébergée

KOBO_RETRY_ATTEMPTS

Nombre de tentatives sur throttling/erreur serveur (défaut 3)

KOBO_RETRY_BASE_DELAY_MS

Délai initial du backoff exponentiel (défaut 700)

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

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

  1. « Liste mes formulaires Kobo »

  2. « Charge les données du formulaire X » → Claude voit les questions et la qualité des données

  3. « Quelles régions ont le plus de parcelles en mauvais état ? » → croisements

  4. « 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:watch

Notes 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_form est irréversible : il exige confirm: true et, si le formulaire contient des données, le nombre exact de soumissions. Pour simplement arrêter une collecte, utilise kobo_archive_form.

  • kobo_set_sharing avec anonymous_submissions=true rend 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 push

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

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

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

  2. Les rapports restent sur le serveur — ils sont écrits dans le KOBO_OUTPUT_DIR de la machine hôte, et il n'existe pas d'endpoint de téléchargement pour les récupérer.

  3. MCP_ACCESS_KEY est 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 start

L'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 tools
kobo_analyzeDescriptive Statistics of KoboToolbox DataA
Read-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 FormA
Idempotent

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 QuestionsA
Read-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 FormA
DestructiveIdempotent

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

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

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 SetupA
Read-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 AttachmentsA
Read-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 ExcelA
Read-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 XLSFormA
Read-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 HistoryA
DestructiveIdempotent

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_data_sampleRead Cleaned KoboToolbox RowsA
Read-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 DetailsA
Read-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 SubmissionA
Read-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 XLSFormA
Destructive

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 FormsA
Read-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 SubmissionsA
Read-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 DataA
Read-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 FormA
DestructiveIdempotent

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

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

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

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

    A4.1/5.0

    Scored across 27 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      B
      quality
      Not graded
      maintenance
      A 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.
      23
      1
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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 npm
      MIT