Content
<p align="center">
<img src="docs/assets/hero.svg" alt="Open Emirates Intelligence" width="900">
</p>
<h1 align="center">Open Emirates Intelligence</h1>
<p align="center">
<a href="https://github.com/ahmedvnabil/uaemcp/actions/workflows/ci.yml"><img src="https://github.com/ahmedvnabil/uaemcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://www.npmjs.com/package/uaemcp"><img src="https://img.shields.io/npm/v/uaemcp?logo=npm" alt="npm version"></a>
<a href="https://www.npmjs.com/package/uaemcp"><img src="https://img.shields.io/npm/dm/uaemcp?logo=npm" alt="npm downloads"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-server-000000" alt="MCP"></a>
<a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white" alt="Python"></a>
<a href="ts"><img src="https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white" alt="TypeScript"></a>
</p>
<p align="center"><em>Official UAE open data, as MCP tools any agent can call — hosted or self-hosted.</em></p>
<p align="center">
<img src="docs/assets/demo.gif" alt="npx uaemcp — live terminal demo" width="760">
</p>
A **standalone MCP server** that gives any MCP client (Claude Desktop, Claude Code,
Cursor) source-cited access to **official UAE open data** — with direct-contact PII
redacted, every server-side fetch SSRF-guarded, and both **stdio** and **HTTP**
transports in one package.
It is self-contained: no dependency on any private or sibling service. Ships in two
flavors: a **Python** implementation (this directory) and a **TypeScript / npm**
port ([`ts/`](ts)) published as [`uaemcp`](https://www.npmjs.com/package/uaemcp).
---
## Two ways to use it
Open source under the **MIT license** — use the instance we host, or run your own.
### 1. Use our hosted instance — zero setup
A public instance is live at **https://uaemcp.zad.tools**. Point any
MCP client at its endpoint — nothing to install:
```json
{
"mcpServers": {
"uae-intelligence": {
"type": "http",
"url": "https://uaemcp.zad.tools/mcp"
}
}
}
```
Or just open the dashboard: <https://uaemcp.zad.tools>
### 2. Self-host it — run your own, anywhere
- **npm, no install:** `npx uaemcp` (stdio) · `npx uaemcp http` (HTTP at `/mcp`)
- **Docker:** `docker build -t uaemcp . && docker run -p 8080:8080 uaemcp uaemcp http`
- **From source:** clone this repo (Python below, or the TypeScript port in [`ts/`](ts))
Self-hosting gives you full control: add your own sources, set a write token, and
keep every fetch on your own infrastructure.
---
## Quickstart
### Fastest — via npm (no install)
```bash
npx uaemcp # stdio MCP server
npx uaemcp http # Streamable-HTTP server at /mcp
```
### Local (stdio) — for an MCP client
The published npm package is the easiest way to run it in a client:
```json
{
"mcpServers": {
"uae-intelligence": { "command": "npx", "args": ["-y", "uaemcp"] }
}
}
```
To run the **Python** implementation from source instead:
```bash
pip install -e .
uaemcp stdio
```
### Remote (HTTP) — landing page + REST + MCP endpoint
```bash
uaemcp http --host 0.0.0.0 --port 8080
```
- Landing page: `http://localhost:8080/`
- REST API: `http://localhost:8080/api/v1/...`
- MCP (Streamable): `http://localhost:8080/mcp`
- Liveness/readiness: `/healthz`, `/readyz` (cheap — no upstream calls)
---
## Showcase
The hosted dashboard is **bilingual (EN / العربية)** and styled with the official
**Dubai Font**:
<p align="center">
<img src="docs/assets/landing-en.png" alt="Landing page (English)" width="49%">
<img src="docs/assets/landing-ar.png" alt="Landing page (Arabic, RTL)" width="49%">
</p>
Interactive API docs — Dubai-Font-themed Swagger UI at [`/docs`](https://uaemcp.zad.tools/docs):
<p align="center">
<img src="docs/assets/swagger.png" alt="Dubai-Font Swagger UI" width="90%">
</p>
## Tools
| Tool | Kind | Description |
|------|------|-------------|
| `uae_sources_list` | read | List every registered official source |
| `uae_source_get` | read | Full metadata for one source |
| `uae_source_health` | read | Live, timeout-bounded health probe |
| `uae_source_records` | read | Live, redacted, cited records |
| `uae_market_snapshot` | read | Counts by emirate / area / product |
| `uae_dashboard_summary` | read | Concurrent, cached health across all sources |
| `uae_source_add_metadata` | **write** | Add a metadata source (token required) |
Every data-returning tool wraps results in `{ ok, data, error, meta }` and attaches
`source_id`, `license`, and `citation`.
## Usage examples
### Ask your MCP client (natural language)
Once connected, just ask — the client picks the right tool:
- *"List UAE industrial factories licensed in Abu Dhabi."* → `uae_source_records`
- *"Give me a market snapshot of UAE industry by emirate."* → `uae_market_snapshot`
- *"Which official UAE open-data sources can you access?"* → `uae_sources_list`
- *"Is the Dubai Land Department data source up right now?"* → `uae_source_health`
### Call a tool over HTTP (Streamable-HTTP MCP)
```bash
# initialize → grab the mcp-session-id header, then call tools/list, tools/call
curl -s -X POST https://uaemcp.zad.tools/mcp/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"uae_market_snapshot","arguments":{"topic":"industry","limit":50}}}'
```
### Or hit the REST mirror directly
```bash
# 32 registered sources
curl -s https://uaemcp.zad.tools/api/v1/sources | jq '.meta.total'
# live, PII-redacted records from the MOIAT industrial-licenses API
curl -s 'https://uaemcp.zad.tools/api/v1/sources/moiat_industrial_licenses/records?limit=2'
```
```jsonc
// sample record (contact fields are redacted by default)
{
"CompanyName": "…",
"EmirateNameEN": "Abu Dhabi",
"AreaNameEN": "Musaffah Industrial",
"ContactPhone": "[redacted-open-data-contact]",
"ContactEmail": "[redacted-open-data-contact]"
}
```
Interactive API docs (Dubai-Font themed Swagger UI): <https://uaemcp.zad.tools/docs>
## Security model
- **Writes gated.** Reads are open; mutating tools require `UAEMCP_WRITE_TOKEN`.
No token set → writes are disabled entirely (safe default).
- **SSRF guard.** Every fetch resolves the host and rejects private, loopback,
link-local, and cloud-metadata addresses. See [`core/ssrf.py`](src/uaemcp/core/ssrf.py).
- **PII redaction.** Phone/email fields are redacted by name and by value pattern
before any record leaves the server.
- **Bounded fetches.** Browser-like User-Agent (so bot-mitigated portals don't hang),
strict timeouts, capped redirects and response size.
## Design notes — what this fixes vs. the prior version
- **No auth on writes** → token-gated writes, disabled by default.
- **SSRF surface** → mandatory `validate_url` on every egress.
- **stdio-only** → real remote MCP at `/mcp`.
- **`dashboard-summary` stall** → checks run **concurrently** with a strict
per-source timeout and a browser UA, served from cache. Worst case is the
slowest single source, not the sum of all.
- **Cold-start 502** → `/healthz` and `/readyz` do no upstream work.
## Development
```bash
pip install -e ".[dev]"
pytest -m "not network" # offline unit tests (ssrf, redaction, dashboard)
pytest # include live-endpoint integration tests
ruff check . && mypy src
```
## License
MIT. Data served is open government data — verify each source's terms before
redistribution.
