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