Skip to content

dhis2w

Python tooling for DHIS2. A uv workspace with an async client library, a Typer CLI, a FastMCP server, a Playwright browser helper, a code generator, and a shared plugin runtime.

Where to start

Everything here talks to DHIS2. Pick the surface you want to talk to it through — each has its own tab, its own tutorial, and its own reference:

  • Python client — async library for ETL scripts, embedded DHIS2 calls inside another service, and tests that need typed access. Pairs with the Python library tutorial.
  • d2w CLI — terminal use, shell pipelines, CI / cron jobs, day-to-day admin. Pairs with the CLI tutorial.
  • dhis2w-mcp MCP server — LLM-driven workflows (Claude Desktop, Claude Code, Cursor, Continue, Cline). Pairs with the MCP tutorial.
  • d2w fhir — publish an instance's metadata as a FHIR Implementation Guide, serve it as a capture endpoint, and forward what it captures back into DHIS2. Graded 100-501, opening at the introduction; start at the Introduction.

Whichever you pick:

Packages

Package Role PyPI
dhis2w-client Async DHIS2 API client with pluggable auth and pydantic models dhis2w-client
dhis2w-core Profile discovery, plugin registry, first-party plugins dhis2w-core
dhis2w-cli Typer console script d2w (mounts plugins from dhis2w-core) dhis2w-cli
dhis2w-mcp FastMCP server dhis2w-mcp (mounts the same plugins) dhis2w-mcp
dhis2w-mcp-bridge Single-tool MCP bridge exposing the d2w CLI for small local models dhis2w-mcp-bridge
dhis2w-browser Playwright helpers (PAT creation, future UI automation) dhis2w-browser
dhis2w-codegen Version-aware client generator workspace-only
dhis2w-bench Model benchmarking harness workspace-only
dhis2w-mcp-router Search + dispatch over upstream MCP servers dhis2w-mcp-router
dhis2w-fhir d2w fhir: generate an Implementation Guide from an instance, convert captures, drain the spool dhis2w-fhir
dhis2w-fhir-serve The FHIR capture facade d2w fhir serve runs on, capture UI included dhis2w-fhir-serve
dhis2w-fhir-engine FHIRPath, CQL, and quality-measure evaluation over FHIR data, no DHIS2 dependency dhis2w-fhir-engine

Plus infra/, a docker-compose stack for running a local DHIS2 instance with pre-seeded PATs and an OAuth2 client.

Capability matrix

The generated MCP reference currently reports around 318 tools across 15 plugin groups (the auto-regenerated count is the source of truth; the per-group numbers below age with each release). 20 top-level CLI domains. Every MCP tool accepts an optional profile: str | None kwarg so an agent can target any configured profile per call. Most operational read/write commands ship as both a CLI command and a matching MCP tool sharing one typed service call. A few surfaces are intentionally CLI-only — they involve local-machine state, interactive prompts, or out-of-process subprocesses that don't fit the MCP stdio model:

  • d2w dev — codegen, sample-fixture generation, ad-hoc UID minting. Local developer workflow; not exposed via MCP.
  • d2w browser — Playwright-driven PAT mint, OIDC login, dashboard / viz / map screenshots. Runs Chromium out-of-process; not exposed via MCP.
  • d2w profile add / remove / rename / login / logout / bootstrap — profile mutations touch local TOML + the OAuth2 token store and gate on interactive prompts. Profile reads (list, verify, show) are exposed as MCP tools; the four MCP profile tools cover those read paths.
  • d2w fhir — scaffolds project trees, shells out to a dockerized IG publisher, and runs its own HTTP facade. The plugin registers no MCP tool at all; the served facade is the network surface an agent talks to instead.
Domain CLI MCP tools Docs
Profile (list / verify / show / default / add / remove / rename, login / logout / bootstrap) d2w profile 4 Profiles
System (whoami, info, server-info, calendar get/set) d2w system 5 System module
Metadata — core surface (list / get / patch / search / usage / export / import / diff / diff-profiles / merge) d2w metadata 230 Metadata plugin
Metadata — authoring triples (org-units, data-elements, indicators, program-indicators, category-options + legend-sets + options + attribute + program-rule + sql-view + viz + dashboard + map) d2w metadata <sub-app> — (part of metadata count above) Organisation units / Data elements / Indicators / Program indicators / Category options / Legend sets
Data (aggregate dataValueSets + dataValues, tracker entities / enrollments / events / relationships / push) d2w data aggregate + d2w data tracker 15 Aggregate plugin / Tracker plugin
Analytics (aggregate / event / enrollment / outlier / tracked-entity queries) d2w analytics 5 Analytics plugin
Route (/api/routes integration proxies) d2w route 7 Auth schemes
Maintenance (tasks, cache, cleanup, data integrity, validation, predictors) d2w maintenance 15 Maintenance plugin
Files (documents + file resources) d2w files 5 Files plugin
Data store (namespaces, keys, get / set / delete, delete-namespace, the shared store and the per-user one) d2w datastore 5 Data store
Messaging (/api/messageConversations + ticket-workflow fields) d2w messaging 11 Messaging plugin
User admin (users, groups, roles, sharing) d2w user + d2w user group + d2w user role 16 User plugin / User groups + roles
Customize (login page / logos / CSS / system settings) d2w customize 7 Customize plugin
Apps (/api/apps + /api/appHub + snapshot/restore) d2w apps 13 Apps API
Doctor (BUGS tripwires + integrity checks + metadata health) d2w doctor 4 Doctor plugin
Security posture (settings, authorities, audit, report) d2w security 3 Security plugin
Dev (codegen, uid, pat, oauth2 client, sample fixtures) d2w dev — (dev-only) Codegen
Browser automation (Playwright-driven PAT mint, screenshots, OIDC login) d2w browser — (runs out-of-process) Browser automation
FHIR (init / validate / generate / serve / forward / withdraw / doctor) d2w fhir — (CLI and its own HTTP facade) d2w fhir

Day-to-day workflows (make install, make lint, make test, make docs-serve) are documented in the repo root README.md.