Townshipamerica

PyPI License: MIT

Model Context Protocol (MCP) server that exposes Township America's PLSS and Texas TXSS conversion tools to AI agents — Claude, ChatGPT, Cursor, GitHub Copilot, Windsurf, or any MCP-compatible client.

Also includes a Python client (TownshipMCPClient) for scripts and notebooks, backed by the townshipamerica SDK.

API Documentation · GitHub · PyPI · npm (Node)

Requires a Pro+ subscription ($99/mo) for bundled API access.

Installation

pip install townshipamerica-mcp

Requires Python 3.10+.

Quick Start

Set your API key (generate at app.townshipamerica.com/settings/api-keys):

export TOWNSHIP_AMERICA_API_KEY="ta_…"

Tools

Tool	Description
plss_to_coordinates	Convert a PLSS or Texas TXSS description to GPS
coordinates_to_plss	Reverse-lookup coordinates to a legal description
plss_to_geojson	Return the tract polygon/multipolygon as GeoJSON
validate_description	Validate and normalize locally (PLSS + TXSS, no API)
batch_convert	Convert up to 100 descriptions in one request
autocomplete	Suggestions for partial PLSS or TXSS input (max 10)

Coverage: 30 PLSS states, 37 principal meridians, and all 254 Texas counties (TXSS). Powered by BLM CadNSDI V2 and Texas GLO survey data.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "townshipamerica": {
      "command": "townshipamerica-mcp",
      "env": {
        "TOWNSHIP_AMERICA_API_KEY": "ta_…"
      }
    }
  }
}

Restart Claude Desktop to apply.

Cursor / VS Code / Continue

{
  "mcpServers": {
    "townshipamerica": {
      "command": "townshipamerica-mcp",
      "env": { "TOWNSHIP_AMERICA_API_KEY": "ta_…" },
    },
  },
}

Stdio (any MCP client)

TOWNSHIP_AMERICA_API_KEY=ta_… townshipamerica-mcp

Environment variables

Variable	Default	Purpose
TOWNSHIP_AMERICA_API_KEY	(required)	Your Pro+ API key (preferred)
TA_API_KEY	—	Legacy alias for TOWNSHIP_AMERICA_API_KEY
TOWNSHIP_AMERICA_BASE_URL	https://developer.townshipamerica.com	Override the API endpoint
MCP_LOG_LEVEL	INFO	Log level for stderr

Quota

Pro+ bundled API access: 1,000 search calls/month. If exceeded, tools return a clear quota message with upgrade guidance. Visit townshipamerica.com/pricing.

Python client

For programmatic use without an MCP host:

from townshipamerica_mcp import TownshipMCPClient

client = TownshipMCPClient(api_key="ta_…")

result = client.plss_to_coordinates("NW 25 24N 1E 6th Meridian")
print(result.lat, result.lng)

v = client.validate_description("NW 25 24N 1E 6th Meridian")
print(v.valid, v.normalized)

batch = client.batch_convert(["NW 25 24N 1E 6th Meridian", "SE 12 4N 5E Boise Meridian"])
print(batch.converted, batch.failed)

For full SDK features (async, GeoPandas-friendly models), use pip install townshipamerica.

Exceptions

Exception	Trigger
AuthenticationError	Invalid or missing API key
QuotaExceededError	Rate limit / quota exceeded
NotFoundError	Location not in PLSS database
ValidationError	Malformed request
TownshipMCPError	Base class / other errors

License

MIT — see LICENSE.