🗺️ Census Geocoding MCP

An MCP (Model Context Protocol) server that gives AI assistants full access to the U.S. Census Bureau Geocoding Services API. Geocode addresses, reverse-geocode coordinates, and retrieve Census geographies — all without an API key.

✨ Features

• 🔓 No API key required — the Census Geocoding API is completely free and public

• 📍 Single-record geocoding — one-line or parsed addresses (stateside + Puerto Rico)

• 🗂️ Geography lookup — resolve addresses or coordinates to Census tracts, blocks, counties, congressional districts, and more

• 📦 Batch processing — up to 10,000 records per request, as CSV or structured arrays

• 🌐 Puerto Rico support — dedicated endpoints with Urbanization and Municipio fields

• 🏛️ Benchmark & vintage control — target specific MAF/TIGER database versions and Census geography vintages

• 🟦 TypeScript — fully typed, ESM, Node.js ≥ 18

Related MCP server: chuk-mcp-geocoder

🧰 Tools (12 total)

🔍 Discovery

📌 Single-Record Geocoding (Locations)

🗺️ Single-Record Geography Lookup

📦 Batch Processing

🚀 Quick Start

Prerequisites

• Node.js ≥ 18.0.0

Install & Build

git clone https://github.com/your-username/census-geocoding-mcp.git
cd census-geocoding-mcp
npm install
npm run build

Add to Claude Desktop

Edit your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "census-geocoding": {
      "command": "node",
      "args": ["/absolute/path/to/census-geocoding-mcp/dist/index.js"]
    }
  }
}

Restart Claude Desktop — the 12 geocoding tools will be available immediately.

🛠️ Tool Reference

list_benchmarks

Lists all available benchmarks (MAF/TIGER locator database versions).

No parameters required.

list_vintages

Lists all vintages available for a given benchmark.

geocode_oneline_address

Geocode a complete address provided as a single string.

Returns: matched address, interpolated coordinates, Tigerline ID, address range components.

geocode_parsed_address

Geocode a US stateside address with fields parsed separately. Requires at minimum street + zip OR street + city + state.

geocode_pr_address

Geocode a Puerto Rico address with optional Urbanization and Municipio.

find_geographies_oneline / find_geographies_parsed / find_geographies_pr

Same parameters as their geocode_* counterparts, plus:

Geography layers returned include: States, Counties, Census Tracts, Census Blocks, Congressional Districts, County Subdivisions, Incorporated Places, State Legislative Districts, Urban Areas, Combined Statistical Areas, and more.

find_geographies_coordinates

Reverse geocode a coordinate pair to Census geographies.

batch_geocode_locations

Batch geocode up to 10,000 addresses. Accepts either raw CSV or a structured array.

csv_content takes precedence if both are provided. At least one must be supplied.

Returns CSV columns: Record ID, Input Address, Match Indicator, Match Type, Output Address, Coordinates, Tigerline ID, Tigerline Side.

batch_geocode_geographies

Like batch_geocode_locations but also returns Census geography codes.

Additional parameter:

Returns CSV columns: all location columns + State Code, County Code, Tract Code, Block Code.

batch_geolookup_coordinates

Batch geography lookup for coordinate pairs.

💡 Example Prompts

Once connected to Claude Desktop, try prompts like:

• "What Census tract and block is 1600 Pennsylvania Avenue NW, Washington DC in?"

• "Geocode these 500 addresses and give me their lat/lon coordinates" (paste a CSV)

• "What congressional district is at longitude -87.6298, latitude 41.8781?"

• "List all available Census geocoding benchmarks"

• "Geocode this Puerto Rico address: 123 Calle Luna, Urb El Paraíso, San Juan, PR 00926"

⚙️ Development

# Watch mode (recompile on save)
npm run dev

# One-time build
npm run build

# Run the server directly
npm start

📋 Notes & Limits

• Batch limit: 10,000 records per file — enforced client-side before the request is sent; exceeding it raises a clear error immediately

• Batch size limit: CSV content is additionally capped at 5 MB (UTF-8 bytes) — this catches oversized inputs that could pass the row count check via very long lines

• No authentication required — all endpoints are public

• Single-record responses are JSON; batch responses are CSV text

• Default benchmark: Public_AR_Current (current MAF/TIGER database)

• Default vintage: Current_Current (required for all geography endpoints)

• Request timeout: all API calls time out after 30 seconds; the server raises an abort error rather than hanging indefinitely

• Input length validation: all string parameters have maximum lengths enforced before any network request is made (address 200 chars, street/city/urb/municipio 100, state/zip 10, benchmark/vintage 50, layers 500)

• Coordinate validation: longitude must be in [-180, 180] and latitude in [-90, 90]; out-of-range values are rejected before the request is sent

• CSV field escaping: address fields passed to batch endpoints are escaped per RFC 4180 (embedded quotes doubled, fields containing commas or newlines quoted) to prevent malformed CSV

• The underlying API is provided by the U.S. Census Bureau and subject to their terms of service

📚 References

• Census Geocoding Services API Specification

• Model Context Protocol

• @modelcontextprotocol/sdk

⚖️ License

This project is licensed under the MIT License.