Skip to main content
Glama

@gener8v/mcp-geographic-data

MCP server for the loc8n Geographic Data API. Exposes U.S. demographics, housing, mortgage, migration, employment, and geographic data as tools for any MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.).

Quick Start

npm install -g @gener8v/mcp-geographic-data

Set your API key:

export LOC8N_API_KEY="your-api-key"

Get a key at loc8n.com.

Related MCP server: civic-library-mcp

Usage

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "geographic-data": {
      "command": "mcp-geographic-data",
      "env": {
        "LOC8N_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "geographic-data": {
      "command": "mcp-geographic-data",
      "env": {
        "LOC8N_API_KEY": "your-api-key"
      }
    }
  }
}

Hosted SSE (no install required)

Connect any MCP-compatible client directly to the hosted server at mcp.loc8n.com. Pass your API key as a query parameter or Authorization header:

SSE endpoint: https://mcp.loc8n.com/sse?apiKey=YOUR_API_KEY

Or with a Bearer token:

GET https://mcp.loc8n.com/sse
Authorization: Bearer YOUR_API_KEY

Each connection gets an isolated session — your API key is used for all requests and usage is tracked against your account.

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "geographic-data": {
      "url": "https://mcp.loc8n.com/sse?apiKey=YOUR_API_KEY"
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "geographic-data": {
      "serverUrl": "https://mcp.loc8n.com/sse?apiKey=YOUR_API_KEY"
    }
  }
}

Self-Hosted SSE

Run the server locally for development or custom deployments:

mcp-geographic-data --transport sse --port 3100

Endpoints:

  • SSE: http://localhost:3100/sse

  • Messages: http://localhost:3100/messages

  • Health: http://localhost:3100/health

Tools (23)

Geographic Lookup

Tool

Description

lookup_zip_code

Get details for a ZIP code (city, county, state, coordinates)

search_zip_codes_by_city

Find ZIP codes for a city/state

find_zip_codes_in_radius

Find ZIP codes within a radius of a point

calculate_zip_code_distance

Calculate distance between two ZIP codes

search_areas

Search counties, states, or metro areas by name

Demographics

Tool

Description

get_demographics

Full demographic profile (population, income, education, etc.)

get_demographics_category

Single demographic category in detail

get_demographics_trend

Year-over-year demographic trends

compare_demographics

Side-by-side comparison of two areas

Housing & Market Data

Tool

Description

get_fair_market_rent

HUD Fair Market Rent by bedroom count

get_fmr_trend

Fair Market Rent trends over time

Mortgage & Lending

Tool

Description

get_mortgage_summary

HMDA mortgage origination summary

get_mortgage_trends

Mortgage lending trends over time

compare_mortgage

Side-by-side mortgage comparison of two areas

Migration

Tool

Description

get_migration_summary

IRS SOI migration inflows/outflows

get_migration_flows

Top origin/destination flows for an area

get_migration_trends

Migration trends across year pairs

Employment

Tool

Description

get_employment

LODES employment profile (jobs, sectors, wages)

get_employment_trend

Employment trends over time

compare_employment

Side-by-side employment comparison

get_commute_flows

Top commute origins/destinations

Geocoding

Tool

Description

geocode_address

Convert address to coordinates and FIPS codes

reverse_geocode

Convert coordinates to address and area identifiers

Resources (7)

URI

Description

data://demographics/available-years

Available years for ACS demographics data

data://fmr/available-years

Available years for HUD Fair Market Rent data

data://mortgage/available-years

Available years for HMDA mortgage data

data://migration/available-years

Available year pairs for IRS migration data

data://employment/available-years

Available years for LODES employment data

data://tiers

Subscription tier definitions and permissions

data://auth/context

Current API key tier, permissions, and rate limits

Environment Variables

Variable

Required

Default

Description

LOC8N_API_KEY

Yes

—

API key for the loc8n Geographic Data API

LOC8N_API_BASE_URL

No

https://api.loc8n.com

API base URL

CLI Options

mcp-geographic-data [options]

  --transport <stdio|sse>  Transport protocol (default: stdio)
  --port <number>          Port for SSE transport (default: 3100)
  --help, -h               Show help

License

MIT

Available Tools

23 tools
calculate_zip_code_distanceA
Read-onlyIdempotent

Calculate the distance between two ZIP codes using either the Haversine or Vincenty formula. Returns origin/destination details and the computed distance.

Inputs: to (required), from (required), unit, method.

compare_demographicsA
Read-onlyIdempotent

Compare demographics side by side for two to ten ZIP codes. Returns each ZIP's demographic profile plus summary comparison ranges (population, income, housing).

Inputs: zip_codes (required), data_year, categories.

compare_employmentA
Read-onlyIdempotent

Compare employment data for multiple areas side by side (2-10 areas). All geoids must share the same area type. Returns per-area metrics including total jobs, industry mix, earnings, and age breakdown.

Inputs: geoids (required), area_type (required), year, perspective.

compare_mortgageA
Read-onlyIdempotent

Compare mortgage lending metrics across 2-5 geographic areas for a single HMDA data year. All areas must be the same geographic level (tract, county, or state). Returns side-by-side summaries including origination count, denial rate, median loan amount, and loan type/purpose breakdowns for each area. Source: CFPB/FFIEC HMDA.

Inputs: geoids (required), area_type (required), year.

find_zip_codes_in_radiusA
Read-onlyIdempotent

Find all ZIP codes within a given radius of a center ZIP code. Returns each nearby ZIP with its distance from the center.

Inputs: radius (required), zipCode (required), sort, unit, +1 more.

geocode_addressA
Read-onlyIdempotent

Convert a street address or place name into geographic coordinates. Returns up to 'limit' candidate results with coordinates, formatted address, address components, confidence score, and provider name. The optional 'country' parameter biases (but does not strictly filter) results toward the given country.

Inputs: address (required), limit, country.

get_commute_flowsA
Read-onlyIdempotent

Retrieve commute flow (origin-destination) data for a county or state. Shows where workers come from (inbound) or where residents commute to (outbound). Returns top flow pairs with job counts and a 3-supersector industry breakdown (Goods Producing, Trade/Transport/Utilities, All Other Services). Note: this uses OD data with a coarser industry breakdown than the 20-sector NAICS detail available in single-area employment summaries. Not available at the tract level.

Inputs: geoid (required), area_type (required), direction (required), year, +2 more.

get_demographicsA
Read-onlyIdempotent

Retrieve a full demographic profile (population, income, housing, education, employment, households) for a single geographic area such as a ZIP code, county, state, place, CBSA, census tract, or block group.

Inputs: area_code (required), area_type (required), data_year.

get_demographics_categoryA
Read-onlyIdempotent

Retrieve specific demographic categories (e.g. population, income, housing) for a geographic area. Use this instead of get_demographics when you only need a subset of categories to keep the response concise.

Inputs: area_code (required), area_type (required), categories (required), data_year.

get_demographics_trendA
Read-onlyIdempotent

Retrieve historical demographic data across multiple years for a single geographic area, useful for analysing population growth, income changes, or housing trends over time.

Inputs: area_code (required), area_type (required), end_year, start_year.

get_employmentA
Read-onlyIdempotent

Retrieve employment data for a single geographic area. Returns total jobs, industry mix by NAICS sector, earnings distribution, and age breakdown. The 'perspective' parameter controls whether data reflects jobs physically located in the area (workplace, WAC data — default) or jobs held by the area's residents regardless of where they work (residence, RAC data).

Inputs: geoid (required), area_type (required), year, perspective.

get_employment_trendA
Read-onlyIdempotent

Retrieve employment data across all available years for a single area. Returns an array of yearly metrics (total jobs, industry mix, earnings, age breakdown) ordered ascending by year. Use 'perspective' to choose workplace (default) or residence.

Inputs: geoid (required), area_type (required), perspective.

get_fair_market_rentA
Read-onlyIdempotent

Look up HUD Fair Market Rent (FMR) rates for a geographic area by ZIP code, county FIPS, CBSA/metro code, or state FIPS. Returns monthly rent estimates by bedroom count (efficiency through 4-bedroom). Note: State-level queries return all ZIP-level FMR records within the state, which can be hundreds of records. Use ZIP or county lookups when only a single area is needed. Source: U.S. Dept. of Housing & Urban Development, Fair Market Rents.

Inputs: area_code (required), area_type (required), year.

get_fmr_trendA
Read-onlyIdempotent

Retrieve Fair Market Rent data across multiple years for a single area. Returns an array of yearly FMR records with rent values by bedroom count. Supports ZIP, county, and CBSA area types. State-level trends are not supported because state queries return aggregated lists of ZIP-level records, not a single time series. Source: U.S. Dept. of Housing & Urban Development, Fair Market Rents.

Inputs: area_code (required), area_type (required), end_year, start_year.

get_migration_flowsA
Read-onlyIdempotent

Retrieve top inflow or outflow areas for a county or state, ranked by number of tax returns or AGI. Inflows show where people moved from (into this area); outflows show where people moved to (out of this area). Returns an array of flow records with FIPS, area name, returns, exemptions, and AGI (in thousands of dollars). Some flow entries may be suppressed by the IRS for privacy when returns fall below the disclosure threshold. Source: IRS Statistics of Income.

Inputs: fips (required), level (required), direction (required), sort, +2 more.

get_migration_summaryA
Read-onlyIdempotent

Retrieve migration summary for a county or state showing aggregate inflows, outflows, and net migration. Returns net returns (positive = net in-migration, negative = net out-migration), net exemptions (proxy for people), and net AGI (adjusted gross income in thousands of dollars). Year is specified as a year pair (e.g., '2021-2022') representing tax filing year transitions. Source: IRS Statistics of Income.

Inputs: fips (required), level (required), year.

get_mortgage_summaryA
Read-onlyIdempotent

Retrieve the mortgage lending summary for a single geographic area (census tract, county, or state) from HMDA data. Returns origination count, denial rate, median loan amount, median interest rate, loan purpose mix, and loan type mix (conventional, FHA, VA, USDA). Source: CFPB/FFIEC HMDA.

Inputs: geoid (required), area_type (required), year.

lookup_zip_codeA
Read-onlyIdempotent

Look up full details for a single 5-digit US ZIP code, including city, state, county, timezone, coordinates, area codes, land/water area, and elevation.

Inputs: zipCode (required).

reverse_geocodeA
Read-onlyIdempotent

Convert a latitude/longitude coordinate pair into a street address. Returns the best-match formatted address, address components, and coordinates.

Inputs: latitude (required), longitude (required).

search_areasA
Read-onlyIdempotent

Search for geographic areas by name across all boundary types (county, state, CBSA, census tract, ZIP). Uses trigram matching for fuzzy name search.

Inputs: query (required), limit, types.

search_zip_codes_by_cityA
Read-onlyIdempotent

Search for all ZIP codes in a given city and state. Returns the full list of matching ZIP codes with details.

Inputs: city (required), state (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 23 tools

    Disambiguation5/5

    Every tool targets a distinct resource and action. The parallel families (demographics, mortgage, migration, employment) each have clear single-area, trend, and compare variants, so there is no ambiguity in purpose.

    Naming Consistency5/5

    All tool names follow a clean snake_case verb_noun pattern (lookup_zip_code, get_demographics, compare_employment, geocode_address). The names use consistent domain terminology, with only minor use of standard acronyms like FMR.

    Tool Count3/5

    23 tools is on the heavier side and falls into the 16-25 border historically considered 'heavy'. However, the breadth of geographic data covered (ZIP, demographic, housing, mortgage, migration, employment, geocoding) justifies each tool's existence.

    Completeness5/5

    The server provides comprehensive read-only coverage for its domain: single lookups, searches, trends, comparisons, and geocoding both directions. There are no obvious dead ends or missing operations needed for typical analytic workflows.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides complete world location data (countries, states, cities) as an MCP server for AI assistants, enabling search and retrieval of geographic information through 11 tools and 5 resources.
      719 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Remote MCP server exposing US Census (ACS 5-year) and FEMA flood data. Works as a connector in both Claude and ChatGPT.
      -