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¶
Pick the surface that matches what you're building:
- 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.
d2wCLI — terminal use, shell pipelines, CI / cron jobs, day-to-day admin. Pairs with the CLI tutorial.dhis2w-mcpMCP server — LLM-driven workflows (Claude Desktop, Claude Code, Cursor, Continue, Cline). Pairs with the MCP tutorial.
Other entry points:
- New to the repo? Skim the Walkthrough, set up a local DHIS2, then pick a surface above.
- Connecting to a remote DHIS2? Connecting to DHIS2 covers Basic / PAT / OAuth2 with profiles.
- Looking for the architecture? Start at Overview, then Typed schemas + Codegen.
- Browsing by symbol? The API reference auto-renders every
dhis2w-clientmodule's docstrings.
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-browser |
Playwright helpers (PAT creation, future UI automation) | dhis2w-browser |
dhis2w-codegen |
Version-aware client generator | workspace-only |
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 304 tools across 13 plugin groups (the auto-regenerated count is the source of truth; the per-group numbers below age with each release). 18 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.
| 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 |
Messaging (/api/messageConversations + ticket-workflow fields) |
d2w messaging |
11 | Messaging plugin |
| User admin (users, user-groups, user-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 |
| 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 |
Day-to-day workflows (make install, make lint, make test, make docs-serve) are documented in the repo root README.md.