international-jobs-mcp

A small MCP server that lets Claude search current UN, NGO, and international-organization job postings — UNDP, UNICEF, UNHCR, WFP, IOM, WHO, FAO, OCHA, and hundreds of NGOs/IGOs — via the official ReliefWeb API.

Why ReliefWeb, and not UN Careers / Impactpool / Devex?

Those sites don't publish a public API, and scraping them would be fragile and against most of their Terms of Service. ReliefWeb (run by UN OCHA) is the one major hub in this space that offers a free, official, read-only API — and it already aggregates postings from most UN agencies plus a huge number of NGOs, so it covers the same ground legitimately.

What it gives Claude

• search_international_jobs — search/filter by keyword, country, organization, career category; open or expired postings; pagination.
• get_international_job_details — full description + how-to-apply for one posting.
• list_career_categories — current valid category filter values with live open-posting counts (e.g. "Programme/Project Management", "Information and Communications Technology", "Logistics/Procurement" — all relevant to your PM/ERP background).

⚠️ Before you do anything else: get an appname

Since Nov 2025, ReliefWeb requires a pre-approved appname for all API calls (it's free, just needs their sign-off):

1. Go to https://reliefweb.int/contact (or find the "request an appname" form linked from https://apidoc.reliefweb.int/parameters).
2. Describe it as a personal tool querying the Jobs API. Include an org/purpose string + random characters as your appname, per their instructions.
3. Wait for their approval email — this is the one step only you can do, since it needs your contact details.

Step 1 — Smoke-test the API (do this first)

I wrote server.py against ReliefWeb's documented field-naming conventions (country.name, source.name, etc.) but couldn't test it against the live API from my sandbox — api.reliefweb.int isn't in my reachable network. Once you have your appname, run this first:

pip install httpx
export RELIEFWEB_APPNAME="your-approved-appname"
python test_api.py

If any field name is wrong, ReliefWeb's error response names the bad field directly — cross-check against https://apidoc.reliefweb.int/fields-tables and fix it in server.py (search for the fields.include lists — there are three of them).

Step 2 — Run it locally

pip install -r requirements.txt
export RELIEFWEB_APPNAME="your-approved-appname"
python server.py                 # stdio — for local testing with MCP Inspector
# or
python server.py --http          # streamable HTTP on :8000 — for remote/Claude use

Test it with the official inspector before deploying anywhere:

npx @modelcontextprotocol/inspector

Step 3 — Deploy it somewhere with a public HTTPS URL

Claude's custom connectors need a reachable HTTPS URL, so pick one:

Option A — Render (fastest, free tier, good for a first pass)

1. Push this folder to a GitHub repo.
2. On render.com: New → Web Service → connect the repo.
3. Environment: Docker (it'll pick up the included Dockerfile automatically).
4. Add environment variable RELIEFWEB_APPNAME = your approved appname.
5. Deploy — Render gives you a URL like https://your-app.onrender.com.

Option B — Railway (similarly quick)

1. railway init in this folder, then railway up.
2. Set RELIEFWEB_APPNAME in the Railway dashboard's Variables tab.
3. Railway gives you a public URL automatically.

Option C — Azure Container Apps (matches your RELAINE stack)

Since RELAINE already runs on Azure with GitHub Actions:

az group create --name international-jobs-mcp-rg --location eastus
az containerapp up \
  --name international-jobs-mcp \
  --resource-group international-jobs-mcp-rg \
  --source . \
  --target-port 8000 \
  --ingress external \
  --env-vars RELIEFWEB_APPNAME=your-approved-appname

You can wire this into the same GitHub Actions pattern you already use for RELAINE if you want CI/CD on every push.

Step 4 — Add it to Claude as a custom connector

In claude.ai: Settings → Connectors → Add custom connector, then paste your deployed URL with the MCP path (check your server's startup log for the exact mount path — FastMCP's streamable HTTP transport defaults to /mcp, so it's typically https://your-app.onrender.com/mcp).

Once connected, you can ask me things like "search UN jobs in project management, Tanzania or remote" and I'll call search_international_jobs directly — same as the Jobs and Careers connector, but pointed at the UN/NGO/international-org space instead of the US commercial market.

Notes / honesty check

• Rate limits: ReliefWeb caps this at 1000 calls/day and 1000 results per call — generous for personal use.
• remote_only is a soft filter (adds remote/home-based keywords to the text search) — ReliefWeb has no hard structured "remote" flag like the US jobs tool does, so treat it as a nudge, not a guarantee.
• If you later want UN Careers or Impactpool coverage specifically, that would require either an official partnership/API access from them, or scraping — which I'd steer you away from building, since it's fragile and against their terms.