DHIS2 MCP Server

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.

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.