census-geocoding-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@census-geocoding-mcp geocode 1600 Pennsylvania Ave NW, Washington DC"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
πΊοΈ 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: Parcel-GIS-mcp
π§° Tools (12 total)
π Discovery
Tool | Description |
| List all available MAF/TIGER locator database versions |
| List vintages (Census geography versions) for a given benchmark |
π Single-Record Geocoding (Locations)
Tool | Description |
| Geocode a full address on one line |
| Geocode a US (stateside) address with separate fields |
| Geocode a Puerto Rico address (supports Urbanization & Municipio) |
πΊοΈ Single-Record Geography Lookup
Tool | Description |
| Geocode a one-line address + return Census geographies |
| Geocode a parsed address + return Census geographies |
| Geocode a PR address + return Census geographies |
| Look up Census geographies for a lon/lat coordinate pair |
π¦ Batch Processing
Tool | Description |
| Batch geocode up to 10,000 addresses (coordinates only) |
| Batch geocode up to 10,000 addresses + Census geographies |
| 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 buildAdd to Claude Desktop
Edit your Claude Desktop configuration file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%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 |
| string | β | Benchmark name or ID (e.g. |
geocode_oneline_address
Geocode a complete address provided as a single string.
Parameter | Type | Required | Description |
| string | β | Full address, e.g. |
| string | β | Default: |
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 |
| string | β | House number and street name |
| string | β | City name |
| string | β | 2-letter state abbreviation |
| string | β | 5-digit ZIP code |
| string | β | Default: |
geocode_pr_address
Geocode a Puerto Rico address with optional Urbanization and Municipio.
Parameter | Type | Required | Description |
| string | β | House number and street name |
| string | β | Urbanization name |
| string | β | City name |
| string | β | Municipio name |
| string | β | ZIP code (begins with 006, 007, or 009) |
| string | β | Default: |
find_geographies_oneline / find_geographies_parsed / find_geographies_pr
Same parameters as their geocode_* counterparts, plus:
Parameter | Type | Required | Description |
| string | β | Default: |
| string | β | Comma-delimited layer names/IDs, or |
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 |
| number | β | Longitude (X) in decimal degrees, range |
| number | β | Latitude (Y) in decimal degrees, range |
| string | β | Default: |
| string | β | Default: |
| string | β | Comma-delimited layer names/IDs, or |
batch_geocode_locations
Batch geocode up to 10,000 addresses. Accepts either raw CSV or a structured array.
Parameter | Type | Required | Description |
| string | β | Raw CSV: |
| array | β | Array of |
| string | β | Default: |
csv_contenttakes 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 |
| string | β | Default: |
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 |
| string | β | Raw CSV: |
| array | β | Array of |
| string | β | Default: |
| string | β | Default: |
π‘ 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 (
address200 chars,street/city/urb/municipio100,state/zip10,benchmark/vintage50,layers500)Coordinate validation:
longitudemust be in[-180, 180]andlatitudein[-90, 90]; out-of-range values are rejected before the request is sentCSV 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
βοΈ License
This project is licensed under the MIT License.
Available Tools
12 toolsbatch_geocode_geographiesA
Batch geocode up to 10,000 addresses AND return associated Census geographies (State, County, Tract, Block Codes). Provide addresses as raw CSV or structured array. CSV format: UniqueID,Street,City,State,ZIP. Returns a CSV with: Record ID, Input Address, Match Indicator, Match Type, Output Address, Coordinates, Tigerline ID, Tigerline Side, State Code, County Code, Tract Code, Block Code.
Inputs: vintage, addresses, benchmark, csv_content.
batch_geocode_locationsA
Batch geocode up to 10,000 addresses (locations only, no Census geographies). Provide addresses either as a raw CSV string or as a structured array. CSV format: UniqueID,Street,City,State,ZIP (all fields except UniqueID and Street are optional but must retain delimiter). Returns a CSV with: Record ID, Input Address, Match Indicator, Match Type, Output Address, Coordinates, Tigerline ID, Tigerline Side.
Inputs: addresses, benchmark, csv_content.
batch_geolookup_coordinatesB
Batch look up Census geographies for up to 10,000 coordinate pairs (longitude/latitude). Provide coordinates as raw CSV or structured array. CSV format: UniqueID,Longitude(X),Latitude(Y). Returns State, County, Tract, and Block codes for each coordinate.
Inputs: vintage, benchmark, coordinates, csv_content.
find_geographies_coordinatesA
Look up Census geographies for a given longitude/latitude coordinate pair. Returns States, Counties, Census Tracts, Census Blocks, Congressional Districts, County Subdivisions, Incorporated Places, State Legislative Districts, Urban Areas, Combined Statistical Areas, and more.
Inputs: latitude (required), longitude (required), layers, vintage, +1 more.
find_geographies_onelineB
Geocode a one-line address AND return associated Census geographies (States, Counties, Census Tracts, Census Blocks, Congressional Districts, County Subdivisions, Incorporated Places, State Legislative Districts, Urban Areas, Combined Statistical Areas, etc.). Requires a benchmark and vintage.
Inputs: address (required), layers, vintage, benchmark.
find_geographies_parsedA
Geocode a parsed US (stateside) address AND return associated Census geographies. At minimum, street and zip OR street, city, and state must be provided. Does NOT support Puerto Rico Urbanization/Municipio.
Inputs: street (required), zip, city, state, +3 more.
find_geographies_prB
Geocode a Puerto Rico address AND return associated Census geographies including Urbanization and Municipio information. To submit without Urbanization, provide at minimum street + zip OR street + city + state. To submit with Urbanization, provide at minimum street + urb + municipio.
Inputs: street (required), urb, zip, city, +4 more.
geocode_oneline_addressA
Geocode a single address provided as one line (e.g. '101 Marietta St, Atlanta, GA, 30303'). Returns matched address, interpolated coordinates, Tigerline ID, and address range components. Missing fields (city, state, ZIP) can be omitted or represented with commas.
Inputs: address (required), benchmark.
geocode_parsed_addressA
Geocode a single US (stateside) address with fields parsed into separate components. Returns matched address, interpolated coordinates, Tigerline ID, and address range components. At minimum, street and zip OR street, city, and state must be provided. Does NOT support Puerto Rico addresses with Urbanization/Municipio.
Inputs: street (required), zip, city, state, +1 more.
geocode_pr_addressA
Geocode a single Puerto Rico address with support for Urbanization and Municipio fields. To submit a PR address without Urbanization, provide at minimum street + zip OR street + city + state. To submit with Urbanization, provide at minimum street + urb + municipio. State is always PR.
Inputs: street (required), urb, zip, city, +2 more.
list_benchmarksB
List all available benchmarks for the Census Geocoder. A benchmark references a version of the MAF/TIGER locator database (e.g. Public_AR_Current, Public_AR_Census2020).
Inputs: no named parameters.
list_vintagesA
List all available vintages for a given benchmark. Vintages reference the Census geography version used for geoLookup (e.g. Current_Current, Census2020_Current). Required when using Find Geographies endpoints.
Inputs: benchmark (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 12 tools
Tools follow a clear two-axis matrix: geocode (coordinates) vs find_geographies (geographies), crossed with input format (oneline/parsed/pr/coordinates) and batch variants. The oneline/parsed/pr trios return the same content for different address formats, so a careless agent could misselect, but descriptions clearly delineate input requirements and PR-specific handling.
Names are predominantly consistent snake_case verb_noun (geocode_oneline_address, find_geographies_pr, batch_geocode_locations). Minor inconsistencies exist (e.g. 'oneline' token placement and the batch_ prefix convention), but the pattern remains predictable and readable.
12 tools is well-scoped for a geocoding API. Each tool earns its place: catalog lookups, three address-format variants, a coordinate lookup, and three batch operations mirror the underlying Census endpoints without redundancy.
The surface covers the full lifecycle: benchmark/vintage discovery, single and batch geocoding, coordinate reverse geolookup, geography lookups, and all address formats including PR Urbanization/Municipio. No obvious dead ends for geocoding workflows.
Maintenance
Related MCP Connectors
US address to census tract, block group, county FIPS and districts, from the Census Geocoder.
Geocode, reverse geocode, and run Overpass spatial queries on OpenStreetMap data.
Geocode, reverse geocode, and run Overpass spatial queries on OpenStreetMap data.
Unofficial Geocodio MCP β wraps the Geocodio geocoding API (geocod.io)
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables access to US Census Bureau TIGERweb geographic boundary data, returning GeoJSON for states, counties, census tracts, places, ZCTAs, and congressional districts.1-
- FlicenseNot gradedqualityDmaintenanceEnables querying public ArcGIS REST services for county/state parcel data, GIS layer identification, and USGS elevation without API keys.-
- AlicenseNot gradedqualityCmaintenanceEnables forward and reverse geocoding of US addresses, returning coordinates and the full Census geography stack with GEOIDs, including batch geocoding of up to 100 addresses.95 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables querying US Census TIGERweb geographic layers such as tracts, blocks, districts, and places, with tools to list layers, run ArcGIS queries, and find every geography containing a given coordinate.94 npmMIT