🗺️ 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

---

🧰 Tools (12 total)

🔍 Discovery

Tool	Description
list_benchmarks	List all available MAF/TIGER locator database versions
list_vintages	List vintages (Census geography versions) for a given benchmark

📌 Single-Record Geocoding (Locations)

Tool	Description
geocode_oneline_address	Geocode a full address on one line
geocode_parsed_address	Geocode a US (stateside) address with separate fields
geocode_pr_address	Geocode a Puerto Rico address (supports Urbanization & Municipio)

🗺️ Single-Record Geography Lookup

Tool	Description
find_geographies_oneline	Geocode a one-line address + return Census geographies
find_geographies_parsed	Geocode a parsed address + return Census geographies
find_geographies_pr	Geocode a PR address + return Census geographies
find_geographies_coordinates	Look up Census geographies for a lon/lat coordinate pair

📦 Batch Processing

Tool	Description
batch_geocode_locations	Batch geocode up to 10,000 addresses (coordinates only)
batch_geocode_geographies	Batch geocode up to 10,000 addresses + Census geographies
batch_geolookup_coordinates	Batch geography lookup for up to 10,000 coordinate pairs

---

🚀 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.

Parameter	Type	Required	Description
benchmark	string	✅	Benchmark name or ID (e.g. Public_AR_Current)

---

geocode_oneline_address

Geocode a complete address provided as a single string.

Parameter	Type	Required	Description
address	string	✅	Full address, e.g. 4600 Silver Hill Rd, Washington, DC, 20233
benchmark	string	➖	Default: Public_AR_Current

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.

Parameter	Type	Required	Description
street	string	✅	House number and street name
city	string	➖	City name
state	string	➖	2-letter state abbreviation
zip	string	➖	5-digit ZIP code
benchmark	string	➖	Default: Public_AR_Current

---

geocode_pr_address

Geocode a Puerto Rico address with optional Urbanization and Municipio.

Parameter	Type	Required	Description
street	string	✅	House number and street name
urb	string	➖	Urbanization name
city	string	➖	City name
municipio	string	➖	Municipio name
zip	string	➖	ZIP code (begins with 006, 007, or 009)
benchmark	string	➖	Default: Public_AR_Current

---

find_geographies_oneline / find_geographies_parsed / find_geographies_pr

Same parameters as their geocode_* counterparts, plus:

Parameter	Type	Required	Description
vintage	string	➖	Default: Current_Current
layers	string	➖	Comma-delimited layer names/IDs, or all

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.

Parameter	Type	Required	Description
longitude	number	✅	Longitude (X) in decimal degrees, range [-180, 180], e.g. -84.39215
latitude	number	✅	Latitude (Y) in decimal degrees, range [-90, 90], e.g. 33.75649
benchmark	string	➖	Default: Public_AR_Current
vintage	string	➖	Default: Current_Current
layers	string	➖	Comma-delimited layer names/IDs, or all

---

batch_geocode_locations

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

Parameter	Type	Required	Description
csv_content	string	➖	Raw CSV: UniqueID,Street,City,State,ZIP per row
addresses	array	➖	Array of {id, street, city?, state?, zip?} objects
benchmark	string	➖	Default: Public_AR_Current

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:

Parameter	Type	Required	Description
vintage	string	➖	Default: Current_Current

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

---

batch_geolookup_coordinates

Batch geography lookup for coordinate pairs.

Parameter	Type	Required	Description
csv_content	string	➖	Raw CSV: UniqueID,Longitude,Latitude per row
coordinates	array	➖	Array of {id, x, y} objects; x (longitude) must be in [-180, 180], y (latitude) in [-90, 90]
benchmark	string	➖	Default: Public_AR_Current
vintage	string	➖	Default: Current_Current

---

💡 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
• 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
• 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 released into the public domain under the Creative Commons Zero v1.0 Universal (CC0 1.0) license.

To the extent possible under law, the author(s) have waived all copyright and related or neighboring rights to this work. You can copy, modify, distribute, and use it without asking permission.