# DHIS2 MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/protocol-MCP-8A2BE2.svg)](https://modelcontextprotocol.io)

Connect **any DHIS2 instance** to Claude and other AI assistants through the
[Model Context Protocol](https://modelcontextprotocol.io). 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

```bash
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

```bash
cp .env.example .env
# edit .env with your instance URL and credentials
```

Try it against the public DHIS2 demo first (no setup needed):

```env
DHIS2_BASE_URL=https://play.im.dhis2.org/stable-2-41-3
DHIS2_USERNAME=admin
DHIS2_PASSWORD=district
```

### 3. Test with MCP Inspector

```bash
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):

```json
{
  "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

```bash
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](LICENSE).

## Acknowledgements

Built for the public health data community. DHIS2 is developed by the
[HISP Centre, University of Oslo](https://dhis2.org). MCP is an open standard
from Anthropic.