kobotoolbox-mcp-server

KoboToolbox MCP サーバー

Model Context Protocol サーバーです。Claude（または任意の MCP クライアント）から KoboToolbox のフィールドデータを直接読み取り、エクスポートできます。

自然な言葉で質問するだけです。「今週、医療対応が必要な受け入れは何件ありましたか？」 や 「このプロジェクトのデータを CSV でエクスポートして」 といった質問に対し、アシスタントが KoboToolbox の稼働中の API に問い合わせて実際の記録から回答します。自分でログインし、ダッシュボードを手作業で操作する必要はありません。

2026 年 7 月時点で、公式 MCP レジストリに KoboToolbox MCP サーバーは存在していませんでした。これが初のサーバーです。

---

KoboToolbox を選ぶ理由

KoboToolbox は、人道支援や開発分野で最も広く使われているデータ収集ツールキットです。オープンソースで無料で利用でき、UNHCR や数千の NGO が、調査、ニーズ評価、モニタリングなどの現場業務に利用しています。多くの場合、通信環境が悪く、専任の IT スタッフもいない地域で使われています。

だからこそ、ここでは MCP サーバーが重要です。KoboToolbox を使う組織は、自分たちのデータを必要に応じて取得・分析できるエンジニアがいない可能性が最も高い組織です。現状では、「今月のデータから実際に何がわかるか？」に答えるには、誰かがログインし、提出データを手作業で絞り込み、スプレッドシートにエクスポートして件数を数える必要があります。このサーバーを使えば、チャットに質問を入力するだけで済み、MCP に対応するアシスタントがチームに代わってツールを操作できるようになります。

開発者向けツールやオフィスアプリ用の MCP サーバーは、すでに数千あります。一方、人道支援の現場で実際に業務に使われているプラットフォーム向けのものはありませんでした。このサーバーがそのギャップを埋めます。

---

できること

KoboToolbox REST API v2 に直接対応した 3 つのツールを提供します。いずれも読み取り・エクスポートのみで、このサーバーがデータを変更または削除することはありません。

ツール	機能	主な入力
list_forms	接続中のアカウントにあるすべてのフォーム／プロジェクトを一覧表示します。名前、UID、デプロイ状況、提出件数を確認できます。	(なし)
get_submissions	1 つのフォームの提出済みレコードを取得します。任意で絞り込み、並べ替え、ページネーションを指定できます。	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 サーバー（eu.kobotoolbox.org）をご利用ください。
• アカウントの API トークン

API トークンの取得

KoboToolbox にログインし、次のいずれかを行います。

• Account Settings → Security → Display から 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 アカウントには、どのようなフォームがありますか？」 「受け入れフォームの最新 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 による入力検証を備えた3つのツールを登録します。stdio 経由で動作します。
• src/kobo-client.ts — KoboToolbox REST API v2 の薄い型付きラッパーです（トークン認証、フォームの一覧表示、送信データの取得、エクスポートの作成後に結果をポーリングするフロー）。

認証情報は環境変数からのみ取得されます。値はハードコードされていないため、同じサーバーを任意の KoboToolbox アカウントやフォームで利用できます。

---

ロードマップ

追加機能の候補：

• 書き込みアクセス（送信データの作成、検証ステータスの編集）
• フォームごとのスキーマ／質問のイントロスペクションにより、アシスタントがフィールドの意味を理解できるようにする
• プライベート／セルフホストの KoboToolbox インスタンスへの対応

ライセンス

MIT