# 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](https://apidoc.reliefweb.int/).

## 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:**

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

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

```bash
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](https://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:
```bash
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.