MCP 服务器

Kobo MCP Server

Enables reading and writing to KoBoToolbox via MCP, including creating forms, deploying them, attaching media, and submitting data, all from chat.

README

Kobo MCP Server

An MCP server that lets Claude (Desktop, Code, or any MCP client) read and write to KoBoToolbox. Create forms from a chat, deploy them, attach media, submit data, all without leaving the conversation.

Forked and extended from PYI-SOE-LTD/kobo-mcp-server, which was read-only. This fork adds 10 new write tools (form creation in JSON or XLSForm, multilingual support, media attachments, deploy, update, clone, submissions).

✨ Features

🌍 Multilingual forms — create surveys in multiple languages at once (e.g. French + Lingala)
📝 Two creation modes — JSON schema (simple) or XLSForm Excel (standard)
🚀 Full lifecycle — create → attach media → deploy → submit → update → redeploy → clone
🖼️ Media attachments — logos, reference images, audio prompts, video, from local file or URL
🔒 Token in .env — never hardcoded, never committed

🧰 16 tools exposed

Read (6)

listProjects · getProjectSummary · getProjectSchema · queryProjectData · getCountsBy · getTimeWindowSummary

Write — forms (7)

createForm · createFormFromXLSForm · deployForm · redeployForm · updateForm · createSubmission · cloneForm

Write — media (3)

attachMedia · listMedia · removeMedia

🚀 Quick start

1. Get a KoBo API token

Global: https://kf.kobotoolbox.org/token/
OCHA/Humanitarian: https://eu.kobotoolbox.org/token/
Self-hosted: https://<your-host>/token/

2. Install

git clone https://github.com/tagnonkoua-ux/kobo-mcp-server.git
cd kobo-mcp-server
pip install -r requirements.txt

3. Configure

cp .env.example .env
# Edit .env and paste your KOBO_TOKEN

4. Register the MCP server in Claude

Claude Code (recommended):

claude mcp add kobo python /absolute/path/to/kobo-mcp-server/mcp_server.py

Or edit ~/.claude.json manually:

{
  "mcpServers": {
    "kobo": {
      "command": "python",
      "args": ["/absolute/path/to/kobo-mcp-server/mcp_server.py"],
      "env": {
        "KOBO_BASE": "https://kf.kobotoolbox.org/api/v2",
        "KOBO_TOKEN": "your_token_here",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

Claude Desktop: copy the same block into claude_desktop_config.json (see claude_desktop_config.json for the template).

💡 On Windows, use double-backslashes in JSON paths: "C:\\Users\\you\\kobo-mcp-server\\mcp_server.py".

5. Restart Claude

The 16 Kobo tools should now appear. Try:

"Create a customer satisfaction survey with 5 questions in French and English, deploy it, and give me the public link."

📐 Simple JSON schema for `createForm`

Mono-lingual

{
  "title": "Customer satisfaction",
  "language": "English (en)",
  "questions": [
    {"name": "your_name", "type": "text", "label": "Your name?", "required": true},
    {"name": "rating", "type": "integer", "label": "Rate us 1-10",
     "constraint": ". >= 1 and . <= 10"},
    {"name": "city", "type": "select_one", "label": "City?",
     "choices": ["Brazzaville", "Pointe-Noire", "Dolisie"]}
  ]
}

Multilingual (label as dict)

{
  "title": "Survey",
  "languages": ["English (en)", "Français (fr)", "Lingala (ln)"],
  "default_language": "Français (fr)",
  "questions": [
    {"name": "name", "type": "text", "required": true,
     "label": {"en": "Your name?", "fr": "Votre nom ?", "ln": "Nkombo na yo ?"}},
    {"name": "city", "type": "select_one",
     "label": {"en": "City?", "fr": "Ville ?", "ln": "Engumba ?"},
     "choices": [
       {"name": "bzv", "label": {"en": "Brazzaville", "fr": "Brazzaville", "ln": "Brazzaville"}},
       {"name": "pnr", "label": {"en": "Pointe-Noire", "fr": "Pointe-Noire", "ln": "Pointe-Noire"}}
     ]}
  ]
}

Supported types

text, integer, decimal, select_one, select_multiple, date, time, datetime, note, geopoint, geotrace, geoshape, image, audio, video, file, barcode, calculate, acknowledge, range, rank, begin_group/end_group, begin_repeat/end_repeat.

Per-question fields

required · relevant (skip logic) · constraint · constraint_message · default · appearance · calculation · read_only · parameters · hint.

🧪 Testing

Run the live test suite against your Kobo account (creates ephemeral forms, cleans them up automatically):

python tests/test_write_ops.py

Expected: 11/11 passed.

The tests cover: list, create (mono & multilingual), deploy, submit, update + redeploy, clone, XLSForm upload, media attach/list/remove.

🔒 Security

Token lives in .env only — .env is .gitignored.
The original upstream repo had a hardcoded token in run.sh. This fork loads from .env instead.
The server logs only the first 6 chars of the token to stderr (e.g. abc123...).
All HTTP goes to your configured Kobo host (default kf.kobotoolbox.org) and KoBoCAT (kc.kobotoolbox.org) for submissions.

If you accidentally leak your token, regenerate it at https://kf.kobotoolbox.org/token/ — the old one stops working instantly.

🌐 Other Kobo instances

Just change KOBO_BASE:

# OCHA / humanitarian
KOBO_BASE=https://eu.kobotoolbox.org/api/v2

# Self-hosted
KOBO_BASE=https://kobo.your-org.example.com/api/v2

The submission code derives the KoBoCAT host automatically by replacing kf. / kpi. with kc. in the hostname.

🛠️ Architecture

kobo-mcp-server/
├── kobo_client.py       # HTTP client for the KPI v2 + KoBoCAT APIs
├── xlsform_builder.py   # JSON → .xlsx XLSForm converter
├── mcp_server.py        # MCP stdio server (16 tools)
├── server.py            # Optional FastAPI HTTP server (legacy)
├── tests/
│   └── test_write_ops.py
├── requirements.txt
├── .env.example
└── README.md