oda-mcp

Read-only Model Context Protocol tools for evidence-based development cooperation and ODA research.

oda-mcp combines public development, humanitarian, health, disaster, and aid-activity sources into compact, provenance-aware country context. Missing, disabled, or failed data is never converted to zero or “no risk.”

Current status

The server supports both local stdio and remote, stateless Streamable HTTP on Node.js 20 or later. The HTTP entrypoint requires bearer-token authentication and Host validation by default, rejects unapproved browser origins, applies per-IP rate limiting, and exposes a separate health endpoint.

ACLED is intentionally not included. Conflict-event integration remains disabled pending a separate review of access, redistribution, attribution, and multi-user service terms.

Related MCP server: unicefstats-mcp

Tools

All tools are read-only. Administrative credentials are configured out of band and are not accepted as tool arguments.

Data sources

• IATI Datastore

• World Bank Indicators and Documents & Reports

• OECD development-finance data

• USGS, GDACS, and NASA EONET

• HDX HAPI

• UNHCR Refugee Statistics

• WHO Global Health Observatory

• ReliefWeb

See DATA_SOURCES.md for source-specific access, licensing, freshness, attribution, and removal considerations.

Install

npm ci

Configure the IATI subscription key through hidden terminal input:

npm run iati:configure
npm run test:iati

On macOS the key is stored in the oda-mcp-iati login-keychain item. Other platforms use a Git-ignored local file with mode 0600. Never paste credentials into chat, MCP tool arguments, URLs, logs, or committed configuration.

Optional integrations:

npm run hapi:configure
npm run reliefweb:configure

UNHCR, WHO, and World Bank endpoints do not require local user credentials.

MCP configuration

Codex:

[mcp_servers.oda-mcp]
command = "node"
args = ["src/mcp-server.mjs"]
cwd = "/absolute/path/to/oda-mcp"
enabled = true

Generic MCP configuration:

{
  "mcpServers": {
    "oda-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/oda-mcp/src/mcp-server.mjs"]
    }
  }
}

Remote Streamable HTTP

Generate a long random bearer token and keep it in the deployment platform's secret store:

openssl rand -hex 32

Run the remote server locally:

MCP_AUTH_TOKEN="replace-with-generated-token" \
MCP_ALLOWED_HOSTS="localhost,127.0.0.1" \
npm run start:http

The endpoints are:

• POST /mcp — stateless Streamable HTTP MCP

• GET /healthz — unauthenticated liveness check with no source or secret details

Deploy the included container behind an HTTPS reverse proxy:

docker build -t oda-mcp .
docker run --read-only --tmpfs /tmp:rw,noexec,nosuid,size=128m --init -p 3000:3000 \
  -e MCP_AUTH_TOKEN="replace-with-generated-token" \
  -e MCP_ALLOWED_HOSTS="mcp.example.com" \
  -e IATI_API_KEY="optional-iati-key" \
  oda-mcp

Set these deployment variables:

For a private server, configure the client with the endpoint URL and an Authorization: Bearer … header. Terminate TLS at the platform load balancer or reverse proxy; do not expose the container directly over plain HTTP.

The pre-shared token mode is intended for a single operator or a small trusted deployment. A public multi-user service still requires MCP OAuth 2.1 authorization, per-user quotas, and a managed audit trail.

Development

npm test
npm audit --omit=dev

The test suite covers credential non-disclosure, fixed upstream hosts, request bounds, source normalization, missing-versus-zero handling, stale-cache behavior, disaster deduplication, and the MCP tool contract.

Security and privacy

• Secrets are injected at runtime and never belong in Git history.

• The data-envelope methodology is versioned independently as oda-mcp-methodology/1.0.0.

• The server sends the IATI key only through the Ocp-Apim-Subscription-Key header to the fixed IATI host.

• External error bodies are sanitized before they reach MCP responses.

• Cached source data may outlive upstream removal until the next refresh; operators must implement and document a removal process.

• Remote mode validates bearer authentication, Host, and browser Origin and applies per-IP rate limits. Public multi-user deployments must replace the shared token with OAuth 2.1, add per-user quotas and audit logging, and use a managed secret store.

Report vulnerabilities through the process in SECURITY.md.

License

Source code is licensed under the Apache License 2.0. Data returned by upstream sources remains subject to each source and publisher’s applicable terms and licences.