MCC-MNC.dev

Mobile country & network codes database

3,042 networks · 227 countries · updated 2026-08

MCC-MNC.dev for AI & LLMs

A clean, licensed telecom dataset and a free REST API, built to plug straight into models and agents. Use it to look up any PLMN (MCC + MNC), detect the country and operators behind a phone number, or run retrieval over 3,042 networks in 227 countries. Everything below is copy-pasteable.

Three ways an LLM or agent typically uses this site:

Install as an MCP server (Claude Code, Codex & more)

MCC-MNC.dev runs a hosted Model Context Protocol server at https://mcc-mnc.dev/mcp. Add it to your coding agent and it gains two tools — mcc_mnc_lookup and mcc_mnc_search — with no local install and no API key (the dataset is public).

Claude Code

One command adds the remote server over HTTP:

# Claude Code — add the hosted MCP server (no install, no API key)
claude mcp add --transport http mcc-mnc https://mcc-mnc.dev/mcp

# then in a session:  "use mcc_mnc_lookup to resolve PLMN 23002"

Codex CLI

Codex speaks MCP over stdio, so bridge to the hosted server with the small mcp-remote proxy: 

# Codex CLI — add to ~/.codex/config.toml
# (bridges the remote HTTP server to Codex's stdio MCP via mcp-remote)
[mcp_servers.mcc_mnc]
command = "npx"
args = ["-y", "mcp-remote", "https://mcc-mnc.dev/mcp"]

Any other MCP client

Cursor, Windsurf, Claude Desktop and others accept the same URL — point a Streamable HTTP MCP server at https://mcc-mnc.dev/mcp (or use mcp-remote where only stdio is supported). Sanity-check it with: 

# Verify the server (JSON-RPC over HTTP):
curl -s https://mcc-mnc.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Tools exposed: mcc_mnc_lookup (by plmn, or mcc+mnc, or mcc) and mcc_mnc_search (free text, ISO code, operator name, or a phone number resolved with libphonenumber).

llms.txt

This site publishes an llms.txt — a small, standardised Markdown file at the domain root that tells language models what the site offers and where the authoritative, model-friendly resources live. Point your crawler, agent or context builder at:

Both are served as text/plain and are safe to ingest whole (a few KB each — they are the index and the reference, not the dataset). For the raw records, use the JSON or CSV downloads instead.

Tool / function schema

A ready-to-paste tool definition — mcc_mnc_lookup — that wraps the /search and /plmn-style endpoints behind one function with parameters q, mcc, mnc and fields. Give the model this schema, then run the tool call against the API with your key.

OpenAI (function calling)

{
  "type": "function",
  "function": {
    "name": "mcc_mnc_lookup",
    "description": "Look up mobile networks by MCC/MNC/PLMN, country, operator or phone number using the free MCC-MNC.dev API. Returns operator, brand, country, ISO codes, dial prefix, status and (for Europe) subscribers and market reach.",
    "parameters": {
      "type": "object",
      "properties": {
        "q": {
          "type": "string",
          "description": "Free-text query: an MCC (\"230\"), PLMN (\"23002\"), country name or ISO code (\"CZ\"), operator/brand (\"O2\"), or a phone number (\"+420601123456\"). Omit when using mcc/mnc."
        },
        "mcc": {
          "type": "string",
          "description": "Mobile country code, 3 digits, e.g. \"230\". Use with mnc for one exact network, or alone for all networks in a country code."
        },
        "mnc": {
          "type": "string",
          "description": "Mobile network code, 2-3 digits, e.g. \"02\". Zero-padding is significant. Requires mcc."
        },
        "fields": {
          "type": "string",
          "description": "Optional comma-separated subset of result fields, e.g. \"plmn,brand,operator,country\"."
        }
      },
      "additionalProperties": false
    }
  }
}

Anthropic (Messages API tools)

{
  "name": "mcc_mnc_lookup",
  "description": "Look up mobile networks by MCC/MNC/PLMN, country, operator or phone number using the free MCC-MNC.dev API. Returns operator, brand, country, ISO codes, dial prefix, status and (for Europe) subscribers and market reach.",
  "input_schema": {
    "type": "object",
    "properties": {
      "q": {
        "type": "string",
        "description": "Free-text query: an MCC (\"230\"), PLMN (\"23002\"), country name or ISO code (\"CZ\"), operator/brand (\"O2\"), or a phone number (\"+420601123456\"). Omit when using mcc/mnc."
      },
      "mcc": {
        "type": "string",
        "description": "Mobile country code, 3 digits, e.g. \"230\". Use with mnc for one exact network, or alone for all networks in a country code."
      },
      "mnc": {
        "type": "string",
        "description": "Mobile network code, 2-3 digits, e.g. \"02\". Zero-padding is significant. Requires mcc."
      },
      "fields": {
        "type": "string",
        "description": "Optional comma-separated subset of result fields, e.g. \"plmn,brand,operator,country\"."
      }
    }
  }
}

Executing the tool call

Map the arguments to one of the three read endpoints, then attach your API key. This handler returns the API's JSON straight back to the model: 

// Resolve the tool call to one of the three read endpoints:
//   mcc + mnc  ->  GET /api/v1/mcc/{mcc}/{mnc}
//   mcc only   ->  GET /api/v1/mcc/{mcc}
//   q          ->  GET /api/v1/search?q={q}
async function mcc_mnc_lookup({ q, mcc, mnc, fields }) {
  const base = 'https://mcc-mnc.dev/api/v1';
  const qs = fields ? '?fields=' + encodeURIComponent(fields) : '';
  let url;
  if (mcc && mnc) url = base + '/mcc/' + mcc + '/' + mnc + qs;
  else if (mcc)   url = base + '/mcc/' + mcc + qs;
  else            url = base + '/search?q=' + encodeURIComponent(q) +
                        (fields ? '&fields=' + encodeURIComponent(fields) : '');
  const res = await fetch(url, { headers: { 'X-API-Key': process.env.MCC_MNC_KEY } });
  if (!res.ok) throw new Error('mcc_mnc_lookup ' + res.status);
  return res.json();
}

Example prompt & agent call

A natural-language request and the tool call it produces:

User: What mobile network does the phone number +420 601 123 456 belong to,
and who owns it? Use the mcc_mnc_lookup tool.

Model -> tool call: mcc_mnc_lookup({ "q": "+420601123456", "fields": "plmn,brand,operator,country,ownership" })

That tool call resolves to a single authenticated HTTP request:

# The tool call above becomes this HTTP request:
curl -H "X-API-Key: mcc_your_key" \
  "https://mcc-mnc.dev/api/v1/search?q=%2B420601123456&fields=plmn,brand,operator,country,ownership"

The response includes a phone analysis (validity, type, E.164, calling code) and a results array of the country's operators — enough for the model to answer "which network and who owns it". Full response shapes are in the API docs and /llms-full.txt.

Skills & integrations

To wrap this as an agent skill or tool, give the agent (1) the tool schema above, (2) a way to store the X-API-Key, and (3) a one-line description of when to reach for it: "telecom lookups — resolve MCC/MNC/PLMN codes, phone numbers and carriers". The three endpoints it needs are /search, /mcc/{mcc} and /mcc/{mcc}/{mnc}; keep fields tight to reduce token cost.

License & attribution

The dataset and all API responses are licensed CC BY-SA 4.0. You may use it commercially, including for training and inference, but you must credit the source and share derived datasets under the same license. A sufficient attribution: 

Data: MCC-MNC.dev (https://mcc-mnc.dev), derived from Wikipedia — CC BY-SA 4.0

See About the data for sources, methodology and honest caveats, and the API documentation for the complete reference.