DHIS2 MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@DHIS2 MCP Server show the ANC 1st visit coverage trend for Dhaka division over the last 12 months"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
DHIS2 MCP Server
Connect any DHIS2 instance to Claude and other AI assistants through the Model Context Protocol. Point it at a URL, give it credentials, and your AI client can explore the org unit hierarchy, search metadata, and pull analytics in plain language. No custom integration per instance.
DHIS2 is the world's largest health information management system, used as the national HMIS in more than 80 countries. This server turns it into a tool your AI assistant can actually query.
What it does
Ask your assistant questions like:
"Connect to our DHIS2 and show the ANC 1st visit coverage trend for Dhaka division over the last 12 months."
and it will resolve the indicator and org unit names to UIDs, run the analytics query, and explain the result. No UIDs, no API syntax, no manual exports.
Related MCP server: MCP-Slicer
Features
Capability | Tools |
Connection |
|
Metadata search |
|
Aggregate data |
|
Tracker / events |
|
Resources | live |
Prompts |
|
Works with any instance via environment variables
Supports personal access tokens or basic auth
Resolves names to UIDs automatically, so users never touch identifiers
Name-resolved, tabular analytics output ready for analysis
Self-signed cert and API-version overrides for national deployments
Quick start
1. Install
git clone https://github.com/ahasan722/dhis2-mcp-server.git
cd dhis2-mcp-server
# with uv (recommended)
uv venv && source .venv/bin/activate
uv pip install -e .
# or with pip
python -m venv .venv && source .venv/bin/activate
pip install -e .2. Configure
cp .env.example .env
# edit .env with your instance URL and credentialsTry it against the public DHIS2 demo first (no setup needed):
DHIS2_BASE_URL=https://play.im.dhis2.org/stable-2-41-3
DHIS2_USERNAME=admin
DHIS2_PASSWORD=district3. Test with MCP Inspector
mcp dev src/dhis2_mcp/server.pyOpen the Inspector, list the tools, and run dhis2_ping. You should see the
instance version come back.
4. Connect to Claude Desktop
Add to your claude_desktop_config.json
(%APPDATA%\Claude\ on Windows,
~/Library/Application Support/Claude/ on macOS):
{
"mcpServers": {
"dhis2": {
"command": "dhis2-mcp",
"env": {
"DHIS2_BASE_URL": "https://play.im.dhis2.org/stable-2-41-3",
"DHIS2_USERNAME": "admin",
"DHIS2_PASSWORD": "district"
}
}
}
}Restart Claude Desktop. The DHIS2 tools appear in the tools menu.
Configuration reference
Variable | Required | Description |
| yes | Instance URL, with or without |
| one of | Personal access token ( |
| one of | Basic-auth credentials |
| no | Pin an API version, e.g. |
| no |
|
| no | Request timeout in seconds (default 60) |
A personal access token is safer than a password and is recommended for shared or hosted deployments.
Example session
You: Is the connection working?
AI: [dhis2_ping] Connected to DHIS2 version 2.41.3.
You: What's the trend of BCG doses given in Bo district last 12 months?
AI: [search_metadata] found indicator "BCG doses given"
[list_org_units] found org unit "Bo"
[get_analytics] periods=LAST_12_MONTHS
Here is the monthly trend ... (table + summary)Architecture
src/dhis2_mcp/
├── config.py # env-driven settings, URL normalisation
├── client.py # httpx wrapper: auth, paging, error handling
├── server.py # FastMCP instance, resources, prompts
└── tools/
├── system.py # connection + instance info
├── metadata.py # name → UID discovery
├── analytics.py # aggregate queries + raw data values
└── tracker.py # events + enrollmentsThe model never needs a UID: every data tool is paired with a metadata search tool, and the server instructions tell the assistant to resolve names first.
Security notes
Credentials are read from the environment, never hard-coded or sent to the model.
Prefer a personal access token scoped to read-only authorities.
.envis git-ignored. Do not commit credentials.This server only reads; it defines no write/delete tools by default.
Development
pip install -e ".[dev]"
pytest # config + import tests (no live instance needed)
ruff check .Roadmap
Write tools (data value import) behind an explicit opt-in flag
Streamable HTTP transport for shared hosting
Caching layer for metadata lookups
Org unit GeoJSON export for mapping
Contributing
Issues and pull requests are welcome. Please open an issue describing the DHIS2 version and use case before large changes.
License
MIT. See LICENSE.
Acknowledgements
Built for the public health data community. DHIS2 is developed by the HISP Centre, University of Oslo. MCP is an open standard from Anthropic.
Available Tools
13 toolsdhis2_api_overviewA
List the main resource collections the instance exposes (data elements, indicators, programs, etc.) so you know what is queryable.
Inputs: no named parameters. Returns: result
dhis2_pingA
Test the connection to the configured DHIS2 instance.
Returns the instance version, revision and server date, or a clear error if the instance is unreachable or credentials are wrong. Call this first when troubleshooting.
Inputs: no named parameters. Returns: result
dhis2_whoamiA
Return the authenticated user: name, username, roles and the organisation units they are assigned to. Useful for confirming which data the account can see.
Inputs: no named parameters. Returns: result
get_analyticsA
Run an aggregate analytics query and return a readable table.
Args: data_dimension: one or more data element / indicator UIDs joined by ';' (semicolon). Find UIDs with search_metadata. org_units: org unit UIDs joined by ';', or a keyword such as USER_ORGUNIT, or a level like LEVEL-2. periods: period values joined by ';'. Accepts fixed periods (202401, 2024Q1, 2024) or relative keywords like LAST_12_MONTHS, THIS_YEAR, LAST_4_QUARTERS, LAST_5_YEARS. output_scheme: NAME (default) for readable labels, or UID.
Example: data_dimension="fbfJHSPpUQD;cYeuwXTCPkU", org_units="ImspTQPwCqd", periods="LAST_12_MONTHS"
Inputs: periods (required), org_units (required), data_dimension (required), output_scheme. Returns: result
get_analytics_rawA
Advanced analytics call with full control over dimensions.
Pass raw dimension strings exactly as the DHIS2 analytics API expects,
e.g. ["dx:UID;UID", "pe:LAST_12_MONTHS", "ou:UID"]. Use filters for
dimensions you want fixed but not shown as columns. Prefer
get_analytics for the common case.
Inputs: dimensions (required), filters, output_scheme. Returns: result
get_data_value_setA
Fetch raw (non-aggregated) data values straight from data entry, for one dataset, period and org unit. Use when you need the exact captured values rather than analytics output.
Args: data_set: dataset UID. period: a single period, e.g. 202401 or 2024Q1. org_unit: org unit UID.
Inputs: period (required), data_set (required), org_unit (required). Returns: result
get_enrollmentsB
Query enrollments (tracked entities entering a program).
Args: program: program UID. org_unit: org unit UID. limit: max enrollments.
Inputs: program (required), org_unit (required), limit. Returns: result
get_eventsA
Query event data for a program via the tracker API.
Args: program: program UID (find it with list_programs). org_unit: org unit UID to scope the query. limit: max events to return. occurred_after: optional ISO date (YYYY-MM-DD) lower bound. occurred_before: optional ISO date (YYYY-MM-DD) upper bound.
Inputs: program (required), org_unit (required), limit, occurred_after, +1 more. Returns: result
list_data_setsB
List datasets (data entry forms) with their period type and the data elements they contain. Use this to discover what aggregate data the instance collects.
Inputs: limit, query. Returns: result
list_org_unitsB
List or search organisation units.
Args: query: optional name filter (case-insensitive substring). level: optional hierarchy level (1=national, higher=more local). limit: max rows.
Inputs: level, limit, query. Returns: result
list_programsA
List tracker and event programs with their stages. Use this before querying tracker/event data.
Inputs: limit, query. Returns: result
org_unit_childrenA
Return the direct children of an organisation unit, for walking the hierarchy down from a district to facilities.
Args: org_unit_id: the parent org unit UID.
Inputs: org_unit_id (required). Returns: result
search_metadataA
Search any metadata collection by name and return matching UIDs.
Args: query: text to match on the object name (case-insensitive). object_type: one of dataElement, indicator, dataSet, program, organisationUnit, categoryOptionCombo, optionSet. limit: max rows to return.
Inputs: query (required), limit, object_type. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool has a clearly distinct purpose: analytics, raw analytics, data values, enrollments, events, metadata search, listings, and system info. No overlap.
Most tools follow a verb_noun pattern (e.g., get_analytics, list_programs), though three tools use a dhis2_ prefix (dhis2_api_overview, dhis2_ping, dhis2_whoami). This minor inconsistency is acceptable.
13 tools is well-scoped for a DHIS2 data reading server, covering metadata, analytics, tracker, and system information without being overwhelming.
Covers core read operations: metadata search, aggregate analytics, raw analytics, data entry values, tracker events/enrollments, and org unit hierarchy. Minor gaps like org unit group analytics are covered by raw analytics, and write operations are out of scope.
Maintenance
Related MCP Connectors
Connect AI clients to your Dactic work context through a hosted MCP service.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Hosted MCP server exposing US hospital procedure cost data to AI assistants
Connect your ads, shop, analytics, social, CRM and finance platforms once, then let Claude, ChatGPT, Cursor or any MCP client read, join and explain your numbers. Public statistics from the World Bank, IMF, Eurostat, OECD, WHO and SEC filings come as context, searchable and chartable from the same tools. Read-only by design, every number carries its source.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that provides health data from the Senechal API to LLM applications, enabling AI assistants to access, analyze, and respond to personal health information.GPL 3.0
- AlicenseAqualityDmaintenanceConnects 3D Slicer with AI assistants through the Model Context Protocol, enabling medical image processing and scene manipulation using natural language.395 PyPI47MIT
- AlicenseNot gradedqualityFmaintenanceA Model Context Protocol server that connects AI tools to Electronic Health Records using SMART on FHIR, allowing secure searching, querying, and analysis of patient data from compatible EHRs.88MIT
- AlicenseAqualityDmaintenanceBridges your Nightscout CGM data with AI assistants via the Model Context Protocol, enabling natural language queries about glucose readings, treatments, statistics, and pattern analysis.21GPL 3.0