Connect

8 clients · secrets stay placeholders

JSON (mcpServers)Claude CodeCodexOpenCodeCursorVS CodeGemini CLIGoose

{
  "mcpServers": {
    "zip-codes": {
      "type": "http",
      "url": "https://mcp.zip-codes.com/mcp",
      "headers": {
        "X-Api-Key": "${X_API_KEY}"
      }
    }
  }
}

claude mcp add --transport http zip-codes https://mcp.zip-codes.com/mcp --header "X-Api-Key: ${X_API_KEY}"

[mcp_servers.zip-codes]
url = "https://mcp.zip-codes.com/mcp"
env_http_headers = { "X-Api-Key" = "X_API_KEY" }

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "zip-codes": {
      "type": "remote",
      "url": "https://mcp.zip-codes.com/mcp",
      "enabled": true,
      "headers": {
        "X-Api-Key": "{env:X_API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "zip-codes": {
      "type": "http",
      "url": "https://mcp.zip-codes.com/mcp",
      "headers": {
        "X-Api-Key": "${X_API_KEY}"
      }
    }
  },
  "deeplink": "cursor://anysphere.cursor-deeplink/mcp/install?name=zip-codes&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbWNwLnppcC1jb2Rlcy5jb20vbWNwIiwiaGVhZGVycyI6eyJYLUFwaS1LZXkiOiIke1hfQVBJX0tFWX0ifX0%3D"
}

{
  "servers": {
    "zip-codes": {
      "type": "http",
      "url": "https://mcp.zip-codes.com/mcp",
      "headers": {
        "X-Api-Key": "${X_API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "zip-codes": {
      "httpUrl": "https://mcp.zip-codes.com/mcp",
      "headers": {
        "X-Api-Key": "${X_API_KEY}"
      }
    }
  }
}

extensions:
  "zip-codes":
    enabled: true
    name: "zip-codes"
    type: streamable_http
    uri: "https://mcp.zip-codes.com/mcp"
    headers:
      "X-Api-Key": "${X_API_KEY}"
    timeout: 300

Placeholders to fill from your own secret store: ${X_API_KEY}. The registry never accepts secret values.

Quality 83 / 100new

protocol88 · weight 25

pass
protocol.modernsupports 2026-07-28 (server/discover)
pass
protocol.statelessanswers without a session
pass
protocol.transportstreamable HTTP
warn
protocol.list_ttltools/list declares ttlMs 0, so clients re-fetch it on every use

authorizationn/a · weight 15

n/a
auth.prm, auth.as_metadata, auth.cimdno remote uses OAuth
n/a
auth.secret_in_urlno templated URL

tool hygiene79 · weight 30

pass
tools.descriptionsevery tool has a description
warn
tools.description_length3 tools have descriptions over 1,024 characters, which crowds the context
pass
tools.schemasevery tool has an object input schema
pass
tools.annotations11 of 11 tools declare readOnlyHint or destructiveHint
fail
tools.directory_hintsno tool declares all four of readOnlyHint, destructiveHint, idempotentHint and openWorldHint; missing: zip_lookup (destructiveHint); zip_facts (destructiveHint); quick_zip (destructiveHint); …
pass
tools.token_costabout 4,967 tokens to load every tool
pass
tools.api_dumptools are not a one-to-one API dump

stabilityn/a · weight 15

n/a
stability.changes, stability.rug_pulltool history recorded for 0 of the 7 days needed

dependenciesn/a · weight 15

n/a
deps.known_vulns, deps.mcp_sdk_version, deps.resolvableno npm or PyPI package

11 tools, about 4,967 tokens to load them all · tool set 88d1fa66a1f9 · checked 2026-10-20 11:08 UTC

Tool changes

No tool definition changes recorded. A server's first observation is its baseline; later probes record what changes.

Checks run on what our credential-free, read-only probes observe; tools are never called and no code audit is performed. How it is computed.

Trust 96 / 100

provenance85

liveness100

freshness100

hygiene100

+repository +dns-namespace +website +reachable +uptime-100% +updated-0d-ago

Derived from observable signals (official registry feed and our own credential-free probes); no code audit performed. How it is computed.

Endpoints

remote	auth	reachable	uptime 30d	p50	protocol	last ok
`https://mcp.zip-codes.com/mcp` streamable-http	none	yes	100%	1394 ms	2026-07-28	2026-10-20

Tools (11)

`about_data`read-only	Where this server's data comes from: for each dataset the authority behind it, the edition served where the source publishes editions (TIGER/Line, ACS, ZCTA), how often a new release is taken, and a ready-made citation string. Costs nothing and needs no key.
`city_name_rules`read-only	How USPS names a ZIP Code, and which of those names may be used on mail. Each ZIP Code has exactly one preferred city name plus alternates, and some alternates are NOT valid for addressing — for 08088 NJ, SHAMONG is valid while SHAMONG TOWNSHIP is not. Returns the rules, the counts and a worked example. Costs nothing and needs no key.
`county_reference`read-only	US counties and county equivalents — all 3,235 of them — with their Census and USPS names, which disagree for over a hundred, plus ANSI code, legal type, land and water area, and USPS delivery footprint. Filter by state to get every county in that state: without a filter only the first 25 are returned, and they are FIPS-ordered, so an unfiltered call answers with Alabama rather than with whatever was asked about. Costs nothing and needs no key.
`distance`read-only	Distance between two places, in miles and kilometres, plus the compass bearing from the first to the second. Each end takes a US ZIP Code, a US ZIP+4, a Canadian FSA, a Canadian postal code, or a latitude,longitude pair, and the two ends can be different kinds — a US ZIP to a Canadian postal code works, and so does a code to a coordinate. Time zone for both ends is included. This is a straight-line distance, not a driving route. Without an API key the distance itself is returned and the geography behind it is withheld.
`metro_area_reference`read-only	US metropolitan and micropolitan statistical areas (CBSAs) — all 935. Of those only 393 are metropolitan; the rest are micropolitan and are NOT metro areas, so do not treat a CBSA count as a metro count. Each carries its divisions, parent combined area, land area and delivery footprint, plus the CMS Medicare labor market area, which is a DIFFERENT geography that shares the same code space. Filter by state to get every area in that state: without a filter only the first 25 are returned, alphabetically, so an unfiltered call answers with Aberdeen. Costs nothing and needs no key.
`quick_zip`read-only	The fast, small answer for a postal code. Takes a US ZIP Code, a US ZIP+4, a Canadian FSA, a Canadian postal code, or a latitude,longitude pair, and returns the code's city, state or province, county, and whether it spans more than one county. Given a ZIP+4 it also returns the street ranges making up that delivery segment; given coordinates it reverse-geocodes to the code containing the point. zip_lookup accepts exactly the same inputs and returns the same ZIP+4 detail — choose this one when the answer only needs to be the code and its place, because the payload is about half the size and only the timezone enrichment is available here. Use zip_lookup for census, demographic, district or American Community Survey enrichments.
`radius_search`read-only	Find every US ZIP Code and Canadian postal area within a radius of a centre point, with the distance to each. The centre takes a US ZIP Code, a US ZIP+4, a Canadian FSA, a Canadian postal code, or a latitude,longitude pair; a ZIP+4 searches from its parent ZIP, and coordinates are used as the point itself, so the centre comes back with no code. Centroid mode measures centre to centre and reaches 500 miles; spatial mode intersects real boundaries, reports how much of each area falls inside, and reaches 250 miles. Set a minimum radius to search a ring rather than a circle. summary.total_count is the number of matches returned; when the list is cut, summary.total_available is the number in the radius and a notice says so. ACS statistics always cover the whole radius. They are aggregates of the ZIP Codes' estimates: est and pct only, with no margin of error or Census column; for one ZIP Code's estimate with its margin of error, use zip_lookup. timezone and ACS come back with the search itself; only census and district data need zip_lookup per ZIP. Without an API key the count and a sample of matches are returned and the rest is withheld; free-tier keys are capped at 100 miles centroid and 50 spatial.
`suggest_places`read-only	Search for a place by partial name, misspelled name, or partial code — the resolver that turns what a person typed into something the other tools can look up. Fuzzy matching is built in: "beverley hills" finds Beverly Hills, "san fransisco" finds San Francisco, and a partial code like "902" finds the ZIP Codes starting with it. Matches US ZIP Codes, cities, USPS city names, counties, metropolitan areas, states, school districts, Canadian FSAs and Canadian postal codes, ranked, with the total number of matches. Reach for this FIRST when the place is vague, misspelled or partial, then pass the resolved code to zip_lookup, radius_search or distance. Restrict the kinds of place with types, or bias results towards a location with near. Coverage is broad rather than deep — it returns names and codes, not the full record.
`validate_address`read-only	Validate and standardise a US street address and return its ZIP+4. US ONLY — unlike the postal-code tools, this does not cover Canada. Send the address on one line in mailing order: number and street, then any unit (APT 4, STE 900, #9), then city, state and ZIP. It tolerates ordinary slips (a misspelling, a missing ZIP, state or directional), but it is not a puzzle to solve: a unit placed after the city or ZIP ("Pensacola FL #9") is ambiguous, a unit or a floor. Send what the user gave you, in proper order, once. If it does not match, report that; do not keep trying rewrites. Returns the address in USPS standard form split into its parts, the 5-digit ZIP and the +4 add-on, a confidence level of high, medium or low (low: the +4 may be withheld), and the county, carrier route, congressional district and census block group for the match, all for one credit. `include` appends more, one credit each: coordinates, the census geographies the address sits inside, its congressional and state legislative districts (now or as of any TIGER/Line year served), its school district, its time zone, and American Community Survey profiles for its census tract. The congressional district already in `details` is USPS's own code for the record; the `cd` append is the mapped district, with its number, name and the congress it belongs to. Always read `notices`. ZIP_CORRECTED means the match is in a different ZIP than the one supplied. SECONDARY_NEEDED means the building has multiple units and an apartment or suite number should be requested. SECONDARY_NOT_VERIFIED means a supplied unit could not be confirmed against known ranges. PARTIAL_MATCH means some details are unverified. A failed match returns success false, sometimes with no notice explaining why, so check success rather than assuming the data block is populated. Without an API key the standardised address is returned with the +4 masked.
`zip_facts`read-only	Statistics about US ZIP Codes and Canadian postal codes: how many exist, how they break down by type, delivery point and carrier route totals, per-state tables, and ranked lists such as the ZIP Codes with the most carrier routes. Every figure is generated from a stored query against the source data, with the date it was measured. Costs nothing and needs no key.
`zip_lookup`read-only	The full record for a postal code — the main location-intelligence tool. Takes a US ZIP Code, a US ZIP+4, a Canadian FSA, a Canadian postal code, or a latitude,longitude pair, and returns the city, state or province, county, whether it spans more than one county, area codes, elevation, metro area and postal details (metro.msa and metro.pmsa are legacy 1999 definitions; the current metro area, the CBSA, comes with census). A ZIP+4 also returns its delivery-segment street ranges, and coordinates reverse-geocode to the code containing the point. Optional enrichments add timezone, census geography, congressional and state legislative districts (for the current year or any TIGER/Line year served), school districts, demographics, Medicare geography and American Community Survey estimates for every release served, all in one schema per year; for Canadian codes, Statistics Canada geography and federal electoral districts (statcan). Use quick_zip instead when only the code and its place are needed — same inputs, about half the payload, no enrichments beyond timezone. Without an API key the core identity fields are returned and everything else is withheld, with each withheld path named.

Schemas: list_tools.

Similar MCP servers

Official server.json

{
  "name": "com.zip-codes/api",
  "title": "Zip-Codes.com Location Intelligence: Spatial Analysis, Districts & 14+ Years of Demographics",
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "remotes": [
    {
      "url": "https://mcp.zip-codes.com/mcp",
      "type": "streamable-http",
      "headers": [
        {
          "name": "X-Api-Key",
          "isSecret": true,
          "description": "Optional API key; without it the server runs in demo mode"
        }
      ]
    }
  ],
  "version": "1.0.0",
  "repository": {
    "url": "https://github.com/ZIP-Codes-API/zip-codes-mcp",
    "source": "github"
  },
  "websiteUrl": "https://www.zip-codes.com/api/mcp",
  "description": "Validate & geocode a US address; enrich with demographics, districts, counties, schools & much more."
}