Unhrdb

MCP Node License: PolyForm Noncommercial

Model Context Protocol server for two UN human-rights corpora, exposed as four read-only tools over one connector:

1. UNHRDB paragraphs — a paragraph-level corpus of UN Treaty Body General Comments, individual-communication jurisprudence, and Special Procedures reports (≈203,000 paragraphs across ≈4,900 documents, citable to the paragraph number).
2. UHRI recommendations — ≈267,000 recommendations and observations addressed to individual UN Member States by the Universal Periodic Review, Treaty Bodies and Special Procedures (2006–present), citable by UN document symbol.

The two corpora are never blended — each tool queries exactly one backend, so a recommendations search can't return a General Comment and vice versa. Ask in plain language ("search the recommendations for…" / "in General Comments only") and the tool descriptions route it.

It runs as a stdio (or HTTP) process and is a thin wrapper over the live HTTP APIs: it adds no index of its own, it just re-exposes the search backends over MCP so any client (Claude Desktop, Claude Code, Cowork) can query them natively.

Companion to the UNHRD search interface and the UHRI+ analytics dashboard.

Try it instantly — no token, no deployment. The server ships pointed at the live public API, so npm install and the Claude Desktop config below are all you need to start querying the corpus. (Self-hosting your own token-gated route is optional — see deploy/RUNBOOK.md.)

Tools

Paragraph corpus (General Comments / jurisprudence / Special Procedures):

Tool	Description
search_paragraphs	Full-text search with scope (gc / jur / sp / all), committee and year filters. Returns verbatim paragraphs with UN signature + ¶ number.
lookup_by_citation	Resolve a citation such as CRC/C/GC/25 ¶12 or A/HRC/61/42 para 10 to its verbatim paragraph. Omit the ¶ number to get document metadata.

UHRI recommendations corpus (State-directed recommendations & observations):

Tool	Description
search_recommendations	Faceted full-text search over ≈267k recommendations. Filters: query, countries, bodies, themes, affected_persons, sdgs, annotation_type, year_start/year_end, page, limit. Returns each item verbatim with UN symbol + body + country + year + annotation_id.
lookup_recommendation	Fetch the full verbatim record for one recommendation by its annotation_id (from a search result) — complete text plus every theme / affected-person / SDG / region label.
list_uhri_facets	List valid filter values (country names, body codes, regions, annotation types, year span). Call it first for exact spellings.

Every result is a verbatim UN paragraph or recommendation with its signature/symbol — no paraphrase, no synthesised text — so answers stay citable to the original UN document.

Two transports

Transport	Entry	Use it for
stdio	src/index.js (npm start)	Claude Code, Claude Desktop — the client spawns it locally
HTTP (Streamable HTTP)	src/http.js (npm run start:http)	Remote clients — Claude Cowork, claude.ai, the connector registry — reach it at a URL

Local clients can't add a URL and remote clients can't spawn a local process, so which transport you need depends on the client. See Remote / HTTP hosting for the URL setup.

Requirements

• Node.js ≥ 18
• Network access to the UNHRDB API

Install

git clone <repo-url> mcp-unhrdb
cd mcp-unhrdb
npm install

Run (standalone test)

node src/index.js
# listens on stdin/stdout; diagnostics on stderr

Or run the end-to-end smoke test (spawns the server, lists tools, calls both):

node test-smoke.js

Configuration (env)

Variable	Default	Notes
UNHRDB_API_BASE	https://150.254.115.204/unhrdb-api/api	Base URL of the paragraph API. Point at …/unhrdb-mcp/api to use the token-gated, independently rate-limited route (see deploy/RUNBOOK.md).
UNHRDB_API_KEY	(empty)	Optional token sent as the X-API-Key header. Required by the hardened /unhrdb-mcp/ route; ignored by the public /unhrdb-api/ route.
UHRI_API_BASE	https://150.254.115.204/uhri-api/api	Base URL of the UHRI recommendations API. Public route needs no key; co-located self-hosting uses http://127.0.0.1:8001/api.
UHRI_API_KEY	(empty)	Optional token for the UHRI API (X-API-Key). The public route ignores it.
UNHRDB_INSECURE_TLS	1	1 accepts the VM's self-signed certificate (applies to both APIs). Set to 0 once the APIs are behind a trusted certificate. The relaxed TLS is scoped to this server's own HTTPS agent — it does not weaken TLS globally.

Wire into Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "unhrdb": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/mcp-unhrdb/src/index.js"]
    }
  }
}

Replace /ABSOLUTE/PATH/TO/ with the directory where you cloned this repo (e.g. the output of pwd from inside it).

Claude Code

claude mcp add-json -s user unhrdb \
  '{"command":"node","args":["/ABSOLUTE/PATH/TO/mcp-unhrdb/src/index.js"]}'

Use -s user for all your projects, or -s local for the current one. To point at a self-hosted token-gated route, add an env block: {"UNHRDB_API_BASE":"https://<host>/unhrdb-mcp/api","UNHRDB_API_KEY":"<token>"}.

Restart Claude Desktop; the two tools appear under the 🔌 menu.

Remote / HTTP hosting

Remote clients (Claude Cowork, claude.ai, the connector registry) connect to a URL, not a local process — so the server has to be hosted. The HTTP entry (src/http.js) serves the same two tools over MCP's Streamable HTTP transport.

Run it with Docker (host networking, so it reaches a co-located UNHRDB API on 127.0.0.1:8002 and listens on 127.0.0.1:8004):

MCP_AUTH_TOKEN=<your-token> docker compose up -d --build
curl -s http://127.0.0.1:8004/health        # {"status":"ok",…}

Front it with TLS + a public path. The repo ships an nginx block at deploy/unhrdb-mcp-rpc.location.conf that exposes it at https://<host>/unhrdb-mcp-rpc/mcp. Clients authenticate with Authorization: Bearer <MCP_AUTH_TOKEN>.

Add that URL as a custom remote connector where your client supports one. The endpoint is stateless (POST /mcp); GET/DELETE return 405.

Notes & limits

• search_paragraphs and search_recommendations return up to limit (≤20) from the requested page; paginate with page for more.
• lookup_by_citation matches on the printed paragraph number (¶N), falling back to internal index, so lettered sub-items resolve correctly.
• search_recommendations accepts clean body codes (CAT, CCPR, UPR) and country names as spelled by list_uhri_facets; multiple values in a filter are OR-combined. themes / affected_persons / sdgs take exact long labels.
• Five read-only tools over two corpora. lookup_recommendation currently resolves an annotation_id; lookup by UN symbol needs a symbol filter on the records API (pending a backend pass). Candidate next tools: get_document (full paragraph text), find_related (embedding neighbours).

License

PolyForm Noncommercial 1.0.0. Research, education, non-profit, and personal use are permitted; commercial use requires a separate licence. See LICENSE. The UNHRDB and UHRI corpora have separate terms.

Citation

Szoszkiewicz, Ł. (2026). mcp-unhrdb: MCP server for UNHRDB and UHRI+ (Version 0.3.1) [Computer software].

Machine-readable citation metadata is available in CITATION.cff.