Kobotoolbox Mcp Server

io.github.drannakurasovaPublished by GitHub account drannakurasovav0.1.0Updated Oct 24, 2026

MCP server for KoboToolbox: list forms, fetch submissions, and export field data.

VerifiedSTDIODesktop onlyFiles & StorageData & Analytics

Overview

AI-generated overview

Lets an assistant list KoboToolbox forms, fetch survey submissions, and export field data as CSV, XLS, GeoJSON, or SPSS labels.

What you can do
Wraps the KoboToolbox REST API v2 in three read-only tools. list_forms lists every form or project in the connected account with name, UID, deployment status, and submission count. get_submissions fetches submitted records for one form with optional filtering, sorting, and pagination. export_form_data starts a server-side export, waits for it to finish, and returns a download URL in csv, xls, geojson, or spss_labels format.
When to use it
Useful when a team collects survey or field data in KoboToolbox and wants to ask questions about live records or pull exports without logging into the dashboard and filtering submissions by hand. Aimed at humanitarian, development, and monitoring workflows where staff may not have engineering support.
Requirements
Runs locally over stdio as an npm package; needs Node.js 18 or later. Requires a KoboToolbox account on the global or EU server and an API token supplied through the KOBO_API_TOKEN environment variable, plus KOBO_SERVER to choose the host. Network access to the KoboToolbox API is required.
Before you install
KOBO_API_TOKEN grants full access to the account's data and should be treated like a password; it is read from the environment and passed to the KoboToolbox API. The server is described as read and export only, so it should not modify or delete records, but exports create server-side export jobs and return download URLs. Form and submission data leaves the local machine for the KoboToolbox host.

Installation

In SourceWeft

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

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

Other MCP clients

Follow the launch instructions in the repository.

README

KoboToolbox MCP Server

A Model Context Protocol server that lets Claude (or any MCP client) read and export field data directly from KoboToolbox.

Ask in plain language — "How many intakes came in this week that need medical attention?" or "Export this project's data as a CSV" — and the assistant queries the live KoboToolbox API and answers from real records, instead of you logging in and clicking through the dashboard by hand.

As of July 2026, no KoboToolbox MCP server existed in the official MCP registry — this is the first.

Why KoboToolbox

KoboToolbox is the most widely used data-collection toolkit in humanitarian and development work. It's open-source, free to use, and runs the field operations of UNHCR and thousands of NGOs — surveys, needs assessments, monitoring — often in places with poor connectivity and no dedicated IT staff.

That last part is exactly why an MCP server matters here. The organizations running on KoboToolbox are the ones least likely to have engineers who can pull and analyze their own data on demand. Today, answering "what does this month's data actually say?" means a person logging in, filtering submissions by hand, exporting a spreadsheet, and counting. This server collapses that into a question typed in chat — and turns any MCP-capable assistant into someone who can operate the tool on the team's behalf.

There are already thousands of MCP servers for developer tooling and office apps. There were none for the platform that humanitarian responders actually run their work on. This closes that gap.

What it does

Three tools, mapped directly onto the KoboToolbox REST API v2. All read/export — this server never modifies or deletes your data.

ToolWhat it doesKey inputs
list_formsLists every form/project in the connected account — name, UID, deployment status, submission count.(none)
get_submissionsFetches the submitted records for one form, with optional filtering, sorting, and pagination.assetUid (required), query, limit, start, sort
export_form_dataKicks off a server-side export, waits for it to finish, and returns a download URL.assetUid (required), format (csv/xls/geojson/spss_labels), fields

Requirements

  • Node.js 18+
  • A KoboToolbox account (free — sign up) on either the global server (kf.kobotoolbox.org) or the EU server (eu.kobotoolbox.org)
  • Your account's API token

Getting your API token

Log into KoboToolbox, then either:

  • Account Settings → Security → Display your API key, or
  • visit https://<your-server>/token/?format=json

Treat this token like a password — it grants full access to your account's data.

Installation

bash
git clone https://github.com/drannakurasova/kobotoolbox-mcp-server.gitcd kobotoolbox-mcp-servernpm installnpm run build

Configuration

Copy the example env file and fill in your token:

bash
cp .env.example .env
env
KOBO_API_TOKEN=your_kobotoolbox_api_token_hereKOBO_SERVER=kf.kobotoolbox.org      # or eu.kobotoolbox.org

Usage

With Claude Desktop

Add this to your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

json
{  "mcpServers": {    "kobotoolbox": {      "command": "node",      "args": ["/absolute/path/to/kobotoolbox-mcp-server/dist/index.js"],      "env": {        "KOBO_API_TOKEN": "your_token_here",        "KOBO_SERVER": "kf.kobotoolbox.org"      }    }  }}

Fully quit and reopen Claude Desktop. The kobotoolbox tools will appear in the tools menu, and you can just ask:

"What forms are in my KoboToolbox account?" "Show me the latest 10 submissions for the intake form." "Export that project's data as a CSV."

With the MCP Inspector

The Inspector is a browser-based test harness — the quickest way to exercise each tool directly (and to record a demo).

bash
npm run inspect

It prints an authenticated URL; open it, click List Tools, select a tool, fill in the inputs, and hit Run Tool.

Development

bash
npm run dev       # run from source with tsx (no build step)npm run build     # compile TypeScript to dist/npm start         # run the compiled servernpm run inspect   # launch the MCP Inspector against the built server

How it works

  • src/index.ts — defines the MCP server and registers the three tools, with input validation via Zod. Runs over stdio.
  • src/kobo-client.ts — a thin, typed wrapper around the KoboToolbox REST API v2 (token auth, form listing, submission fetch, and the create-then-poll export flow).

Credentials come only from environment variables — nothing is hardcoded, so the same server works against any KoboToolbox account or form.

Roadmap

Possible extensions:

  • Write access (create submissions, edit validation status)
  • Per-form schema/question introspection so the assistant understands field meanings
  • Support for private/self-hosted KoboToolbox instances

License

MIT

Source: README.md at commit 9a34c9f

Tools

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

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

50% of the applicable checks met

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

  • Reached in the last 30 days25 pts

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

  • Auth declared10 pts

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

  • Tools listed15 pts

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

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