{
  "markdown": "# KoboToolbox MCP Server\n\n**A [Model Context Protocol](https://modelcontextprotocol.io) server that lets Claude (or any MCP client) read and export field data directly from [KoboToolbox](https://www.kobotoolbox.org).**\n\nAsk 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.\n\n> As of July 2026, no KoboToolbox MCP server existed in the [official MCP registry](https://registry.modelcontextprotocol.io) — this is the first.\n\n<!-- DEMO: replace this line with a GIF or video of the MCP Inspector / Claude Desktop running the tools -->\n<!-- ![Demo](docs/demo.gif) -->\n\n---\n\n## Why KoboToolbox\n\nKoboToolbox 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.\n\nThat 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.\n\nThere 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.\n\n---\n\n## What it does\n\nThree tools, mapped directly onto the KoboToolbox REST API v2. All read/export — this server never modifies or deletes your data.\n\n| Tool | What it does | Key inputs |\n|------|--------------|------------|\n| `list_forms` | Lists every form/project in the connected account — name, UID, deployment status, submission count. | *(none)* |\n| `get_submissions` | Fetches the submitted records for one form, with optional filtering, sorting, and pagination. | `assetUid` (required), `query`, `limit`, `start`, `sort` |\n| `export_form_data` | Kicks off a server-side export, waits for it to finish, and returns a download URL. | `assetUid` (required), `format` (`csv`/`xls`/`geojson`/`spss_labels`), `fields` |\n\n---\n\n## Requirements\n\n- **Node.js 18+**\n- A **KoboToolbox account** (free — [sign up](https://www.kobotoolbox.org/sign-up/)) on either the global server (`kf.kobotoolbox.org`) or the EU server (`eu.kobotoolbox.org`)\n- Your account's **API token**\n\n### Getting your API token\n\nLog into KoboToolbox, then either:\n- **Account Settings → Security → Display** your API key, or\n- visit `https://<your-server>/token/?format=json`\n\nTreat this token like a password — it grants full access to your account's data.\n\n---\n\n## Installation\n\n```bash\ngit clone https://github.com/drannakurasova/kobotoolbox-mcp-server.git\ncd kobotoolbox-mcp-server\nnpm install\nnpm run build\n```\n\n## Configuration\n\nCopy the example env file and fill in your token:\n\n```bash\ncp .env.example .env\n```\n\n```env\nKOBO_API_TOKEN=your_kobotoolbox_api_token_here\nKOBO_SERVER=kf.kobotoolbox.org      # or eu.kobotoolbox.org\n```\n\n---\n\n## Usage\n\n### With Claude Desktop\n\nAdd this to your `claude_desktop_config.json`\n(macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\\Claude\\`):\n\n```json\n{\n  \"mcpServers\": {\n    \"kobotoolbox\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/kobotoolbox-mcp-server/dist/index.js\"],\n      \"env\": {\n        \"KOBO_API_TOKEN\": \"your_token_here\",\n        \"KOBO_SERVER\": \"kf.kobotoolbox.org\"\n      }\n    }\n  }\n}\n```\n\nFully quit and reopen Claude Desktop. The `kobotoolbox` tools will appear in the tools menu, and you can just ask:\n\n> *\"What forms are in my KoboToolbox account?\"*\n> *\"Show me the latest 10 submissions for the intake form.\"*\n> *\"Export that project's data as a CSV.\"*\n\n### With the MCP Inspector\n\nThe [Inspector](https://modelcontextprotocol.io/docs/tools/inspector) is a browser-based test harness — the quickest way to exercise each tool directly (and to record a demo).\n\n```bash\nnpm run inspect\n```\n\nIt prints an authenticated URL; open it, click **List Tools**, select a tool, fill in the inputs, and hit **Run Tool**.\n\n---\n\n## Development\n\n```bash\nnpm run dev       # run from source with tsx (no build step)\nnpm run build     # compile TypeScript to dist/\nnpm start         # run the compiled server\nnpm run inspect   # launch the MCP Inspector against the built server\n```\n\n### How it works\n\n- **`src/index.ts`** — defines the MCP server and registers the three tools, with input validation via [Zod](https://zod.dev). Runs over stdio.\n- **`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).\n\nCredentials come only from environment variables — nothing is hardcoded, so the same server works against any KoboToolbox account or form.\n\n---\n\n## Roadmap\n\nPossible extensions:\n- Write access (create submissions, edit validation status)\n- Per-form schema/question introspection so the assistant understands field meanings\n- Support for private/self-hosted KoboToolbox instances\n\n## License\n\nMIT\n",
  "bytes": 5496,
  "sha": "e58406731e14ec55d5cdbaa2b00250f36e032346ceb8e6819cce2d356819a759",
  "repo_slug": "drannakurasova/kobotoolbox-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_drannakurasova_kobotoolbox_mcp_ee291982/readme"
}