kobotoolbox-mcp-server

KoboToolbox MCP 服务

一个 模型上下文协议 服务，可让 Claude（或任何 MCP 客户端）直接从 KoboToolbox 读取和导出实地数据。

用自然语言提问——“本周有多少条需要医疗救助的接收记录？” 或 “将此项目的数据导出为 CSV”——助手便会查询 KoboToolbox 实时 API，并根据真实记录作答，无需你登录后手动在仪表板中逐项操作。

截至 2026 年 7 月，官方 MCP 注册表中还没有 KoboToolbox MCP 服务——这是第一个。

---

为什么选择 KoboToolbox

KoboToolbox 是人道主义和发展工作中使用最广泛的数据收集工具包。它是开源的，可免费使用，支持 UNHCR 和数千家 NGO 开展实地工作——包括调查、需求评估和监测——这些工作通常在网络连接不佳、没有专职 IT 人员的地方进行。

这正是 MCP 服务在此发挥作用的原因。使用 KoboToolbox 的组织，恰恰是最不可能拥有工程师来随时提取和分析自身数据的组织。如今，要回答“本月的数据实际反映了什么？”这个问题，需要有人登录、手动筛选提交记录、导出电子表格并进行统计。这个服务将这一过程简化为在聊天中输入一个问题——让任何支持 MCP 的助手都能代表团队操作该工具。

开发工具和办公应用已经有数千个 MCP 服务，但服务于人道主义救援人员实际工作平台的 MCP 服务却一个也没有。这个服务填补了这一空白。

---

功能

三个工具，分别对应 KoboToolbox REST API v2。它们只读取和导出数据——此服务绝不会修改或删除你的数据。

工具	功能	主要输入
list_forms	列出已连接帐户中的所有表单/项目——名称、UID、部署状态和提交数量。	(无)
get_submissions	获取某个表单的已提交记录，并支持可选的筛选、排序和分页。	assetUid（必需）、query、limit、start、sort
export_form_data	启动服务端导出，等待导出完成，并返回下载 URL。	assetUid（必需）、format（csv/xls/geojson/spss_labels）、fields

---

要求

• Node.js 18+
• KoboToolbox 帐户（免费——注册），使用全球服务（kf.kobotoolbox.org）或欧盟服务（eu.kobotoolbox.org）
• 帐户的 API 令牌

获取 API 令牌

登录 KoboToolbox，然后任选以下一种方式：

• 前往 帐户设置 → 安全 → 显示，查看你的 API 密钥；或
• 访问 https://<your-server>/token/?format=json

请像对待密码一样保管此令牌——它可完全访问你帐户中的数据。

---

安装

git clone https://github.com/drannakurasova/kobotoolbox-mcp-server.git
cd kobotoolbox-mcp-server
npm install
npm run build

配置

复制示例 env 文件，并填入你的令牌：

cp .env.example .env

KOBO_API_TOKEN=your_kobotoolbox_api_token_here
KOBO_SERVER=kf.kobotoolbox.org      # or eu.kobotoolbox.org

---

使用方法

使用 Claude Desktop

将以下内容添加到你的 claude_desktop_config.json （macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）：

{
  "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"
      }
    }
  }
}

完全退出并重新打开 Claude Desktop。工具菜单中会显示 kobotoolbox 工具，你可以直接提问：

“我的 KoboToolbox 帐户中有哪些表单？” “显示 intake 表单最新的 10 条提交记录。” “将该项目的数据导出为 CSV。”

使用 MCP Inspector

Inspector 是一个基于浏览器的测试工具，可快速直接地调用每个工具（也可用于录制演示）。

npm run inspect

它会输出一个经过身份验证的 URL；打开该 URL，点击 List Tools，选择一个工具，填写输入项，然后点击 Run Tool。

---

开发

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

工作原理

• src/index.ts — 定义 MCP 服务并注册三个工具，通过 Zod 验证输入。通过 stdio 运行。
• src/kobo-client.ts — 为 KoboToolbox REST API v2 提供一个轻量、带类型的封装（令牌身份验证、表单列表、提交内容获取，以及先创建再轮询的导出流程）。

凭据仅从环境变量读取——不会硬编码，因此同一 MCP 服务可用于任何 KoboToolbox 账户或表单。

---

路线图

可能的扩展：

• 写入权限（创建提交内容、编辑验证状态）
• 按表单进行架构／问题探查，让助手理解字段含义
• 支持私有／可自托管的 KoboToolbox 实例

许可证

MIT