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

---

📜 License

MIT — see LICENSE. Original work © PYI-SOE-LTD. Extensions © 2026.

🙏 Credits

• Base server: PYI-SOE-LTD/kobo-mcp-server
• KoBoToolbox API: kobotoolbox/kpi
• MCP protocol: modelcontextprotocol.io