AreaCode.fyi MCP Server
North American (NANP) area-code & phone-number intelligence for AI agents, by areacode.fyi.
Open source Open in the app JSON README (API)
About
North American (NANP) area-code & phone-number intelligence for AI agents, by areacode.fyi.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- riv-lc
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.2
- Last push
- 2026-06-22T15:00:11Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 04:01:18
- Updated
- 2026-08-29 04:01:18
- Origin id
io.github.riv-lc/areacode-mcp
README
# areacode-mcp
**North American (NANP) area-code & phone-number intelligence for AI agents.**
[](https://smithery.ai/servers/riv-lc/area-code)
[](https://www.npmjs.com/package/@riv-lc/areacode-mcp)
An [MCP](https://modelcontextprotocol.io) server that gives Claude, Cursor, and
other agents a small, trusted reference for US & Canada phone numbering — area
codes, NANP validation, local time, city/state coverage, overlays, and
scam/spoofing context. Backed by [**areacode.fyi**](https://areacode.fyi), which
publishes directly from the official NANPA numbering database. Every result
includes a canonical `areacode.fyi` URL and the source date.
> **Scope.** This is area-code-level **reference and education** — not a
> carrier/identity API. It does **not** return a caller's identity, exact
> location, or live/ported carrier, and caller ID can be spoofed, so a number's
> area code never proves who is calling. For caller identity you need a
> carrier-grade (LRN/HLR) provider.
## Install
Run it with `npx` (no install needed) — add it to your client's MCP config.
**Claude Desktop** (`claude_desktop_config.json`) / **Cursor** (`~/.cursor/mcp.json`):
```json
{
"mcpServers": {
"areacode": {
"command": "npx",
"args": ["-y", "@riv-lc/areacode-mcp"]
}
}
}
```
That's it — restart your client and the tools below are available.
Published on the **official MCP Registry** as `io.github.riv-lc/areacode-mcp`, and
on [npm](https://www.npmjs.com/package/@riv-lc/areacode-mcp).
### Remote (hosted) — for ChatGPT, Claude.ai, and web clients
No install. Add the hosted server as a connector URL — same 8 tools, no key:
```
https://mcp.areacode.fyi/mcp
```
(legacy SSE clients: `https://mcp.areacode.fyi/sse`)
## Tools
| Tool | What it does |
| --- | --- |
| `lookup_area_code` | Country, state/province, cities, time zone, current local time, overlays, nearby codes |
| `lookup_phone_number` | Parse/validate a NANP number → area code, region, local time, E.164 |
| `lookup_carrier` | Assigned carrier, line type (wireless/landline), and rate center for a number's NPA-NXX block (block-allocation data, **not** live/ported; covers nearly every US/Canada code) |
| `area_codes_for_city` | Area codes serving a city (optionally disambiguated by state) |
| `area_codes_for_state` | Every area code in a US state or Canadian province |
| `is_scam_area_code` | Scam/spoofing context for an area code + an aggregate of FTC Do Not Call complaints filed about numbers using that code |
| `check_number_reputation` | Unverified community signal (low / mid / high) **plus public FTC Do Not Call complaint data** (count, % robocalls, top subject) for a number |
| `explain_area_code_topic` | Source-backed explainers: neighbor spoofing, overlays vs splits, toll-free, area-code-vs-country-code, temporary numbers |
## Example prompts
- *"A lead entered phone number +1 702-555-0199. Where are they likely located and what time is it there?"*
- *"I got a call from 469 — is that area code suspicious?"*
- *"Which area codes cover Las Vegas?"*
- *"Normalize this list of US/Canada numbers and flag any that are invalid or toll-free."*
- *"Explain neighbor spoofing for a help-center article."*
## Configuration
| Env var | Default | Purpose |
| --- | --- | --- |
| `AREACODE_API_BASE` | `https://areacode.fyi` | Point at a different host (e.g. a self-hosted or staging API) |
## Data & sourcing
Tools call the public `https://areacode.fyi/api/v1` JSON API, which reads the
same dataset the site renders — sourced from the official **North American
Numbering Plan Administrator (NANPA)** database and refreshed monthly. Each
response carries `source`, `canonical_url`, and `data_date` so answers can cite
where the data came from.
The `check_number_reputation` signal is **unverified and crowd-sourced**
(`low` = people looked the number up; `mid`/`high` = it has user reports). It is
never proof that a specific number is fraudulent.
## License
MIT © Reindex Ventures. Built for [areacode.fyi](https://areacode.fyi).