Skip to main content
Glama
DHIS2 MCP Server

DHIS2 MCP Server

by ahasan722

DHIS2 MCP Server

License: MIT Python 3.10+ MCP

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

dhis2_ping, dhis2_whoami, dhis2_api_overview

Metadata search

search_metadata, list_org_units, org_unit_children, list_data_sets, list_programs

Aggregate data

get_analytics, get_analytics_raw, get_data_value_set

Tracker / events

get_events, get_enrollments

Resources

live system/info, relative-period reference

Prompts

explore_instance, indicator_trend

  • 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 credentials

Try 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=district

3. Test with MCP Inspector

mcp dev src/dhis2_mcp/server.py

Open 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

DHIS2_BASE_URL

yes

Instance URL, with or without /api

DHIS2_PAT

one of

Personal access token (d2pat_...)

DHIS2_USERNAME / DHIS2_PASSWORD

one of

Basic-auth credentials

DHIS2_API_VERSION

no

Pin an API version, e.g. 40

DHIS2_VERIFY_SSL

no

false for self-signed certs

DHIS2_TIMEOUT

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 + enrollments

The 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.

  • .env is 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 tools
dhis2_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

    A3.9/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: analytics, raw analytics, data values, enrollments, events, metadata search, listings, and system info. No overlap.

    Naming Consistency4/5

    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.

    Tool Count5/5

    13 tools is well-scoped for a DHIS2 data reading server, covering metadata, analytics, tracker, and system information without being overwhelming.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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
    • A
      license
      Not graded
      quality
      F
      maintenance
      A 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.
      88
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Bridges your Nightscout CGM data with AI assistants via the Model Context Protocol, enabling natural language queries about glucose readings, treatments, statistics, and pattern analysis.
      21
      GPL 3.0