Smalljoe1/dhis2-mcp-server

DHIS2 MCP Server

The DHIS2 MCP Server connects AI tools directly to DHIS2 instances. This gives AI agents, assistants, and chatbots the ability to read and manage DHIS2 data, perform analytics, manage metadata, and automate workflows through natural language interactions.

Use Cases

• Data Management: Submit, retrieve, and validate DHIS2 data entries
• Analytics & Reporting: Generate reports, create visualizations, and analyze health data
• Metadata Management: Manage organization units, data elements, programs, and indicators
• User Administration: Create users, assign roles, and manage permissions
• System Monitoring: Check system status, run maintenance tasks, and monitor performance

Built for health data managers who want to connect their AI tools to DHIS2 context and capabilities.

Quick Start

Prerequisites

1. Go 1.21 or later
2. Access to a DHIS2 instance (demo available at https://play.dhis2.org/dev)
3. MCP-compatible client (VS Code with MCP extension, Claude Desktop, etc.)

Installation

Using Docker (Recommended)

docker run -d \
  -e DHIS2_URL=https://play.dhis2.org/dev \
  -e DHIS2_USERNAME=admin \
  -e DHIS2_PASSWORD=district \
  ghcr.io/smalljoe1/dhis2-mcp-server

Build from Source

git clone https://github.com/Smalljoe1/dhis2-mcp-server
cd dhis2-mcp-server
go build -o dhis2-mcp-server ./cmd/dhis2-mcp-server
./dhis2-mcp-server stdio

MCP Client Configuration

VS Code Configuration

{
  "servers": {
    "dhis2": {
      "command": "./dhis2-mcp-server",
      "args": ["stdio"],
      "env": {
        "DHIS2_URL": "https://your-dhis2-instance.org",
        "DHIS2_USERNAME": "your-username",
        "DHIS2_PASSWORD": "your-password"
      }
    }
  }
}

Available Tools

System Context

• get_system_info - Retrieve DHIS2 system information
• get_me - Get current user profile
• test_connection - Test DHIS2 connectivity

Metadata Management

• get_organisation_units - Retrieve organization units with filtering by level, parent, search term, and limit
• get_data_elements - Retrieve data elements with filtering by search term, domain type, value type, and limit
• search_metadata - Search across multiple metadata objects (organization units, data elements, etc.) with a single query

Data Operations (coming soon)

• get_data_values - Retrieve data values
• submit_data_values - Submit data entries
• validate_data_completeness - Check data completeness

Analytics (coming soon)

• get_analytics_data - Query analytics API
• generate_pivot_table - Create pivot tables
• export_report - Generate and export reports

Environment Variables

• DHIS2_URL - DHIS2 instance URL (required)
• DHIS2_USERNAME - Username for authentication
• DHIS2_PASSWORD - Password for authentication
• DHIS2_TOKEN - Personal access token (alternative to username/password)
• DHIS2_TOOLSETS - Comma-separated list of toolsets to enable
• DHIS2_READ_ONLY - Set to "true" for read-only mode

Development Status

This project is under active development. Current implementation status:

• Basic MCP server structure
• DHIS2 authentication and client
• System context tools
• Metadata tools (organization units, data elements, search)
• Data operations tools (next priority)
• Analytics tools
• Docker deployment
• VS Code integration examples
• Comprehensive documentation

Testing

Test DHIS2 connectivity and functionality:

# Test connection to DHIS2 demo instances
go run ./cmd/test-connection

# Build and run tests
go build -o bin/test-connection.exe ./cmd/test-connection
./bin/test-connection.exe

# Run unit tests
go test ./...

Contributing

Contributions are welcome! Please read our for details.

License

This project is licensed under the MIT License - see the file for details.

Support

• Issues
• Discussions