nigeria-mcp

# Nigeria MCP — Nigerian data for AI agents

**A [Wycord](https://wycord.com) product, built by Braynex Services Ltd.** Author: Samuel Orie. License: **MIT**.

Clean, normalized **Nigerian business & local data** exposed to AI agents (Claude, Cursor, custom agents) as **MCP tools** — one server per data source, each behind a typed provider seam.

> **Status:** 12 servers **LIVE** on npm and on the official **MCP Registry**. Every server returns **live data by default** — no env var to set. 10 are keyless; Bank Resolve and Electricity Meter use live data once their free key is set. Without a key they serve built-in sample data, and every such result is **labelled `[MOCK DATA]`** so it cannot be mistaken for a real figure. (admin-divisions runs fully offline on a bundled dataset — it has no live data source.)

---

## Products

| Server | npm | Tools | Live source | Key? |
|---|---|---|---|---|
| **Trade Intel** | `@wycord/nigeria-mcp-trade-intel` | `get_trade_stats` · `classify_hs` | UN Comtrade | **none** |
| **FX Rates** | `@wycord/nigeria-mcp-fx-rates` | `get_fx_rates` | open.er-api.com | **none** |
| **Bank Resolve** | `@wycord/nigeria-mcp-bank-account` | `resolve_bank_account` · `list_banks` | Paystack | free key |
| **Electricity Meter** | `@wycord/nigeria-mcp-electricity` | `validate_meter` · `list_discos` | VTpass (read-only) | free key |
| **Admin Boundaries** | `@wycord/nigeria-mcp-grid3-boundaries` | `get_boundary` · `point_in_admin` | GRID3 ArcGIS (CC BY 4.0) | **none** |
| **Admin Divisions** | `@wycord/nigeria-mcp-admin-divisions` | `list_states` · `get_lgas` | Bundled dataset (offline) | **none** |
| **Health Facilities** | `@wycord/nigeria-mcp-health-facility` | `find_facilities_near` · `get_facility` | GRID3 NGA Health Facilities v2.0 (CC BY 4.0) | **none** |
| **World Bank Macro** | `@wycord/nigeria-mcp-worldbank-macro` | `get_macro_indicator` | World Bank Indicators API | **none** |
| **IMF WEO** | `@wycord/nigeria-mcp-imf-weo` | `get_imf_projection` | IMF DataMapper API | **none** |
| **UN SDG** | `@wycord/nigeria-mcp-un-sdg` | `get_sdg_indicator` | UN SDG Global Database | **none** |
| **Crypto Tickers** | `@wycord/nigeria-mcp-quidax-crypto` | `get_crypto_ticker` · `list_crypto_markets` | Quidax (read-only) | **none** |
| **Sanctions Screening** | `@wycord/nigeria-mcp-nigsac-sanctions` | `screen_sanctions` | NIGSAC register | **none** |

- **Trade Intel** — Nigeria import/export statistics by partner, commodity and year, **annual or monthly**, with USD value (plus CIF/FOB), net weight and quantity, and commodity breakdowns. Plus HS-code classification.
- **FX Rates** — live Naira rates against USD, EUR and GBP.
- **Bank Resolve** — resolve a 10-digit NUBAN + bank code to the registered account name; list banks with their codes.
- **Electricity Meter** — **read-only** meter validation (customer name/address + DisCo) and the DisCo list. No payments.
- **Admin Boundaries** — Nigeria admin boundaries (state / LGA / ward): centroid, bounding box, and reverse-geocode a lat/lng point to the admin unit that contains it. GRID3 ArcGIS, keyless.
- **Admin Divisions** — Nigeria's 36 states + FCT and all 774 LGAs. Runs **fully offline** on a bundled dataset — no network, no key.
- **Health Facilities** — find Nigerian health facilities near a point, sorted by distance, with details for a single facility. GRID3 NGA Health Facilities v2.0, keyless.
- **World Bank Macro** — Nigerian macro indicators (GDP, inflation, population, remittances, FDI, unemployment) from the World Bank Indicators API. Keyless.
- **IMF WEO** — IMF World Economic Outlook projections for Nigeria (growth, inflation, debt, current account, unemployment) from the IMF DataMapper API. Keyless.
- **UN SDG** — Nigeria UN SDG indicators (poverty, under-5 mortality, electricity & water access, primary completion) from the UN SDG Global Database. Keyless.
- **Crypto Tickers** — live crypto tickers in Naira (BTC/NGN etc.), **read-only**, plus the tradable market list. Quidax public API, keyless.
- **Sanctions Screening** — screen a name against Nigeria's official NIGSAC sanctions register. A **best-effort fuzzy screening signal for human review — not a legal/compliance determination**, and it covers the Nigerian list only. Keyless.

Each server's README has full tool docs, examples and a copy-paste config: see `lanes/<server>/README.md`.
Real-world applications: **[USE_CASES.md](USE_CASES.md)**.

## Install

### One click (Claude Desktop)

Download a bundle from the [latest release](https://github.com/wycord/nigeria-mcp/releases/latest) and double-click it. No terminal, no clone — the bundle carries everything it needs, and the keyed servers prompt you for the free API key during install (leave it blank and they serve labelled sample data).

### Or via npx (any MCP client)

No clone needed (Node.js ≥ 20). Add to your MCP config:

```jsonc
{
  "mcpServers": {
    "nigeria-trade-intel": {
      "command": "npx",
      "args": ["-y", "@wycord/nigeria-mcp-trade-intel"]   // live data, no key, no env
    },
    "nigeria-fx-rates": {
      "command": "npx",
      "args": ["-y", "@wycord/nigeria-mcp-fx-rates"]      // live data, no key, no env
    }
  }
}
```

Then ask: *"What were Nigeria's top crude-oil export partners in 2023?"* or *"What's the dollar to naira rate right now?"*

The keyed servers take their credentials the same way — see [`lanes/bank-account/README.md`](lanes/bank-account/README.md) (free [Paystack](https://paystack.com) key) and [`lanes/electricity/README.md`](lanes/electricity/README.md) (free [VTpass](https://vtpass.com) keys). Without a key these two servers serve built-in sample data, and every result then starts with a `[MOCK DATA: ...]` text block and carries `_meta.dataSource = "mock"`. To force sample data on any server (for tests or offline work), set its provider variable to `mock`, for example `FX_PROVIDER=mock`.

## Configuration

No `.env` file is read. Set a variable in your MCP client's `env` block (or the shell) only when you need to change a default. Every server works with none of them set; the two keyed servers then serve labelled sample data.

| Variable | Server | Default | What it does |
|---|---|---|---|
| `FX_PROVIDER` | FX Rates | `free` | `free` = live; `mock` = labelled sample data |
| `TRADE_PROVIDER` | Trade Intel | `opendata` | `opendata` = live UN Comtrade; `mock` = labelled sample data |
| `BOUNDARY_PROVIDER` | Admin Boundaries | `grid3` | `grid3` = live; `mock` = labelled sample data |
| `HEALTH_PROVIDER` | Health Facilities | `grid3` | `grid3` = live; `mock` = labelled sample data |
| `MACRO_PROVIDER` | World Bank Macro | `worldbank` | `worldbank` = live; `mock` = labelled sample data |
| `IMF_PROVIDER` | IMF WEO | `imf` | `imf` = live; `mock` = labelled sample data |
| `SDG_PROVIDER` | UN SDG | `unsdg` | `unsdg` = live; `mock` = labelled sample data |
| `CRYPTO_PROVIDER` | Crypto Tickers | `quidax` | `quidax` = live; `mock` = labelled sample data |
| `SANCTIONS_PROVIDER` | Sanctions Screening | `nigsac` | `nigsac` = live register; `mock` = labelled synthetic stub |
| `ADMIN_DIVISIONS_PROVIDER` | Admin Divisions | `static` | The only value. Bundled dataset, no network |
| `BANK_PROVIDER` | Bank Resolve | `paystack` if the key is set, else `mock` | `mock` forces labelled sample data |
| `PAYSTACK_SECRET_KEY` | Bank Resolve | unset | Paystack secret key (free). Enables live data |
| `ELECTRICITY_PROVIDER` | Electricity Meter | `vtpass` if all three keys are set, else `mock` | `mock` forces labelled sample data |
| `VTPASS_API_KEY`, `VTPASS_PUBLIC_KEY`, `VTPASS_SECRET_KEY` | Electricity Meter | unset | VTpass keys (free). All three enable live data |
| `VTPASS_BASE_URL` | Electricity Meter | `https://sandbox.vtpass.com/api` | `https://vtpass.com/api` for production |
| `GRID3_STATE_URL`, `GRID3_LGA_URL`, `GRID3_WARD_URL` | Admin Boundaries | GRID3 layers | Override a layer URL |
| `GRID3_HEALTH_URL` | Health Facilities | GRID3 layer | Override the layer query URL |
| `UN_SDG_BASE_URL` | UN SDG | `https://unstats.un.org/sdgapi` | Override the API base URL |
| `NIGSAC_LIST_URL` | Sanctions Screening | `https://nigsac.gov.ng/IndSancList` | Override the list URL |

Mock results are never silent: every tool result starts with a `[MOCK DATA: ...]` text block and carries `_meta.dataSource = "mock"`, and the server prints a warning on stderr at start.

**Outbound hosts.** Every request goes over https to a host the server declares. A URL override (the `*_URL` variables) that points at any other host is refused before a request is made.

| Server | Hosts |
|---|---|
| FX Rates | `open.er-api.com` |
| Trade Intel | `comtradeapi.un.org` |
| Bank Resolve | `api.paystack.co` |
| Electricity Meter | `vtpass.com`, `sandbox.vtpass.com` |
| Admin Boundaries, Health Facilities | `services3.arcgis.com` |
| World Bank Macro | `api.worldbank.org` |
| IMF WEO | `www.imf.org` |
| UN SDG | `unstats.un.org` |
| Crypto Tickers | `app.quidax.io` |
| Sanctions Screening | `nigsac.gov.ng` |
| Admin Divisions | none (offline) |

## Find it on

- **Official MCP Registry** — all 12 servers (new versions of the same names), `io.github.wycord/nigeria-{trade-intel,fx-rates,bank-resolve,electricity,grid3-boundaries,admin-divisions,health-facility,worldbank-macro,imf-weo,un-sdg,quidax-crypto,nigsac-sanctions}`
- **Smithery** — [@braynexservices/nigeria-fx-rates](https://smithery.ai/server/@braynexservices/nigeria-fx-rates) · [trade-intel](https://smithery.ai/server/@braynexservices/nigeria-trade-intel) · [bank-resolve](https://smithery.ai/server/@braynexservices/nigeria-bank-resolve) · [electricity](https://smithery.ai/server/@braynexservices/nigeria-electricity) (4 of the 12 are listed on Smithery today; the 8 newer servers are not listed there yet)
- **Glama** — [glama.ai/mcp/servers/wycord/nigeria-mcp](https://glama.ai/mcp/servers/wycord/nigeria-mcp)
- **npm** — [@braynexservices](https://www.npmjs.com/settings/braynexservices/pack