Skip to main content
Glama
areacode-mcp

areacode-mcp

by riv-lc

areacode-mcp

US and Canada phone-number intelligence for AI assistants. Look up area codes, validate numbers, find the carrier behind a number block, check who texts from a short code, and explain phone scams, with every answer cited to its source.

npm MCP Registry License: MIT

An MCP server backed by areacode.fyi, which publishes directly from the official North American Numbering Plan (NANPA) database. Each result includes a canonical areacode.fyi URL and the date of its data, so your assistant can show where an answer came from.

What you can ask

Ask your assistant

Tool it uses

"A lead entered +1 702-555-0199. Where are they, and what time is it there?"

lookup_phone_number

"I got a call from 469. Is that area code a scam?"

is_scam_area_code

"Who texts from 26266?"

lookup_short_code

"Is 212-217-5500 a cell phone or a landline?"

lookup_carrier

"Which carrier is OCN 9104?"

lookup_ocn

"Which area codes cover Las Vegas?"

area_codes_for_city

"Explain neighbor spoofing for our help center."

explain_area_code_topic

Related MCP server: mcp-phone

Quick start

Hosted server

Use this URL in any client that supports remote MCP servers, such as Claude (custom connectors) or ChatGPT (custom connectors):

https://mcp.areacode.fyi/mcp

The hosted server always runs the latest tools and data. Clients that only speak the older SSE transport can use https://mcp.areacode.fyi/sse.

Claude Code

claude mcp add --transport http areacode https://mcp.areacode.fyi/mcp

Or run the package locally:

claude mcp add areacode -- npx -y @riv-lc/areacode-mcp

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "areacode": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@riv-lc/areacode-mcp"]
    }
  }
}

Any other MCP client

Most desktop clients read an mcpServers block (Claude Desktop uses claude_desktop_config.json):

{
  "mcpServers": {
    "areacode": {
      "command": "npx",
      "args": ["-y", "@riv-lc/areacode-mcp"]
    }
  }
}

Restart the client and the tools are available. The package needs Node.js 18 or later.

Tools

Area codes

Tool

Returns

lookup_area_code

Country, state or province, principal and served cities, time zone, current local time, 10-digit dialing, overlays and nearby codes

area_codes_for_city

The area codes serving a US or Canadian city, with an optional state to tell same-named cities apart

area_codes_for_state

Every area code in a US state or Canadian province

Phone numbers and carriers

Tool

Returns

lookup_phone_number

Whether a number is valid, its E.164 form, area code, region, time zone and current local time

lookup_carrier

The carrier a number's block was assigned to, its line type (cell phone, likely VoIP, or landline or VoIP), its OCN and rate center

lookup_ocn

The carrier behind an OCN (operating company number), or a carrier's OCNs by name, with company type, area codes and number blocks held

Scams and texts

Tool

Returns

is_scam_area_code

Whether an area code is legitimate, spoofing context, and FTC Do Not Call complaint totals for numbers shown with that code

check_number_reputation

FTC Do Not Call complaint data for a number (count, robocall share, top subject, dates) and areacode.fyi's moderated community signal

lookup_short_code

Who texts from a US SMS short code: owner, what the texts are, how to opt out, how often the brand is impersonated, and the owner's own source page

explain_area_code_topic

Sourced explainers: neighbor spoofing, overlays and splits, toll-free numbers, area code vs country code, temporary numbers

Example result

lookup_short_code with {"code": "26266"} (trimmed; the full response adds a safety note):

{
  "code": "26266",
  "owner": "United Airlines",
  "brand": "United Airlines",
  "is_reporting_code": false,
  "what_it_sends": "Flight status alerts for upcoming United trips, including delays and check-in reminders, by text or WhatsApp",
  "category": "other",
  "opt_out": "Text STOP; HELP for United contact info",
  "impersonation_risk": "medium",
  "source": "https://www.united.com/en/us/fly/text-messaging.html",
  "data_date": "2026-11-11",
  "canonical_url": "https://areacode.fyi/short-code/26266"
}

How it works

flowchart LR
  A[Your AI assistant] -->|MCP over stdio| B[npx @riv-lc/areacode-mcp]
  A -->|MCP over HTTP| C[mcp.areacode.fyi]
  B --> D[areacode.fyi/api/v1]
  C --> D
  D --> E[NANPA numbering data]
  D --> F[FTC Do Not Call complaints]
  D --> G[Carrier block records and verified short codes]

The package is a thin client: each tool calls the public areacode.fyi JSON API and returns its response as-is. The hosted server calls the same API inside the site's Cloudflare Worker, so both always return the same answers.

Data sources

Data

Source

Refreshed

Area codes, overlays, time zones

NANPA's official area code database

Weekly

Complaint counts

FTC Do Not Call "Reported Calls" data

Weekly

Carriers, line types, OCNs

Public NPA-NXX block assignments, via localcallingguide.com

Each pull is dated in the response

Short codes

Each owner's own published documentation

Each code carries its verified date

Area-code facts are public records. Methods and definitions: areacode.fyi/methods.

Use it responsibly

  • An area code shows where a number is registered, not who is calling. Caller ID can be spoofed.

  • Carrier data shows the carrier a number block was assigned to. If a number was ported, its current carrier differs.

  • FTC complaint counts are reports consumers filed, not proof that a number's owner did anything wrong.

  • A short code missing from the directory is unverified, not a sign of a scam.

  • areacode.fyi is not a consumer reporting agency. Don't use this data for employment, credit, tenant or insurance decisions (FCRA).

Configuration

Environment variable

Default

Purpose

AREACODE_API_BASE

https://areacode.fyi

Point the package at another host, such as a staging API

The public API has no API key. For high-volume or commercial use, see areacode.fyi/api.

Development

npm ci
npm run build

Try the tools in the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Releasing

npm run release (patch) or npm run release:minor bumps the version, syncs server.json, tags and pushes. The tag runs .github/workflows/release.yml, which publishes to npm through trusted publishing with provenance.

License

MIT © Reindex Ventures. Built for areacode.fyi.

Available Tools

8 tools
area_codes_for_cityArea codes for a cityA

List the area codes that serve a US or Canadian city. Optionally pass a state/province to disambiguate cities that share a name.

Inputs: city (required), state.

area_codes_for_stateArea codes for a state/provinceA

List every area code in a US state or Canadian province.

Inputs: state (required).

check_number_reputationCheck a number's community reputationA

Return the UNVERIFIED, crowd-sourced community signal for a US/Canada number from areacode.fyi: 'low' (people have looked it up), 'mid'/'high' (it has user reports). Caller ID can be spoofed — this is never proof a specific number is fraudulent.

Inputs: number (required).

explain_area_code_topicExplain a phone / area-code topicA

Source-backed explanation of a phone-numbering topic, suitable for answering end users.

Inputs: topic (required).

is_scam_area_codeIs an area code a scam?A

Explain whether an area code is associated with scams. An area code is never a scam by itself; this returns that context plus spoofing notes — caller ID can be faked, so judge calls by what they ask for, not the area code.

Inputs: code (required).

lookup_area_codeLook up an area codeA

Look up a North American (NANP) area code: country, state/province, principal city and served cities, time zone, current local time, 10-digit-dialing flag, overlay codes, and nearby codes. Returns a canonical areacode.fyi URL and the NANPA source date.

Inputs: code (required).

lookup_carrierLook up a number's carrier (assigned block)A

Look up the carrier, line type (wireless/landline), and rate center that a US/Canada number's NPA-NXX block was assigned to. Based on public block-allocation data — NOT a live lookup: if the number was ported the current carrier differs, and coverage currently spans major metros (uncovered area codes return covered:false). Not for caller identity, fraud, or FCRA decisions.

Inputs: number (required).

lookup_phone_numberLook up a phone numberA

Parse and validate a US/Canada (NANP) phone number. Returns whether the format is valid, the E.164 form, the area code, the likely region and time zone, and the current local time there. Area-code level only — NOT the caller's identity, exact location, or live carrier; caller ID can be spoofed.

Inputs: number (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 8 tools

    Disambiguation4/5

    Tools have distinct purposes, but there is some overlap between lookup_area_code and lookup_phone_number (both return area code info) and between check_number_reputation and is_scam_area_code (scam-related). However, each tool serves a specific function and descriptions clarify differences.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern (e.g., area_codes_for_city, lookup_area_code). No mixing of styles or vague verbs.

    Tool Count5/5

    8 tools is well within the ideal range of 3-15. Each tool contributes to the domain of area codes and phone number information without being excessive or insufficient.

    Completeness4/5

    The tool set covers listing area codes by city/state, detailed area code info, phone number parsing, carrier lookup, reputation checks, and scam context. Minor missing features like ZIP-based lookup are not essential for the stated purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables querying telecom routing data (LRN, CNAM, DNO, LERG, toll-free routing) directly from AI assistants like Claude, ChatGPT.
      14
      80 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Validates phone numbers and provides country calling codes, enabling AI agents to look up international dialing codes and filter by country name, ISO code, or calling code.
      102 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Tells your agent whether a number is safe to call or text right now. Live US/Canada phone data: carrier, line type, LRN, CNAM, spam/scam reputation, SMS deliverability, and TCPA 8am–9pm calling-window verdicts, plus bulk jobs. Every query is a fresh network dip, never stale cache. Free sandbox key, no card required. Pay per lookup, no minimums.
      6
      55 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables validating and enriching phone numbers, returning validity, international/national formats, carrier, line type, and country/location data.
      81 npm
      MIT