houston-mcp

A unified Model Context Protocol server for Houston-area civic, transit, and flood data. It joins several incompatible public data systems — city open data, GIS layers, real-time traffic, roadway flood warnings, and transit — behind a small set of workflow-oriented tools, so an AI assistant can answer questions like "is my route flooding right now?" without the model having to know that TranStar, HCFWS, and the GIS hub each speak a different query language.

See PROPOSAL.md for the full project rationale, architecture, and phased plan.

Status: early scaffold. Tool implementations are stubs. See Roadmap.

Why this exists

Existing civic-data MCP servers are generic single-platform wrappers (Socrata-only, CKAN-only). Houston's public data is spread across five incompatible systems, and none of the flood or transit data is reachable by any existing server. See the proposal for the full gap analysis.

Data sources

Source	System	Docs
City of Houston Open Data	CKAN	https://data.houstontx.gov
COH GIS Data Hub	ArcGIS Hub	https://cohgis-mycity.opendata.arcgis.com
Houston TranStar	Custom REST	https://traffic.houstontranstar.org/api/api_doc.aspx
Harris County Flood Warning System	Custom	https://www.harriscountyfws.org
METRO (Houston transit)	GTFS + GTFS-Realtime	https://api-portal.ridemetro.org
Texas Open Data Portal	Socrata	https://data.texas.gov

Installation

# from PyPI (once published)
pip install houston-mcp

# from source
git clone https://github.com/YOUR_USERNAME/houston-mcp.git
cd houston-mcp
pip install -e ".[dev]"

Configuration

Some sources require an API key. Copy .env.example to .env and fill in what you have — tools that need a missing key will report that clearly rather than failing silently.

cp .env.example .env

Variable	Required by	Notes
METRO_API_KEY	transit_arrivals, transit_plan	Sign up at api-portal.ridemetro.org. See Attribution below — required by METRO's terms.
TRANSTAR_API_KEY	flood_status, road_conditions	Optional for public feeds; contact TranStar for elevated access.

Usage with Claude Desktop / Claude Code

Add to your MCP client config:

{
  "mcpServers": {
    "houston": {
      "command": "houston-mcp"
    }
  }
}

Or run directly for development:

python -m houston_mcp.server

Tools

Tool	Purpose	Sources joined
flood_status	Current flooding risk near a location or along a route	TranStar, HCFWS
road_conditions	Closures, incidents, and construction on a corridor	TranStar
transit_arrivals	Real-time arrivals for a stop or address	METRO GTFS-RT
transit_plan	Route options between two points	METRO GTFS
find_dataset	Federated dataset discovery	CKAN, ArcGIS, Socrata
query_dataset	Normalized query against a discovered dataset	CKAN, ArcGIS, Socrata
neighborhood_profile	Permits, 311, district, flood zone for an address	CKAN, ArcGIS
geocode	Address → coordinates → local identifiers	Nominatim

Tool count is capped by design — see PROPOSAL.md §3.1 for why this server favors a small number of workflow tools over one-tool-per-endpoint.

Safety note on flood data

Flood and roadway-condition data in this server is sourced from public feeds that the originating agencies (Houston TranStar, Harris County Flood Control District) explicitly disclaim for accuracy, completeness, and timeliness. This server is informational only and is not an authoritative source for emergency decisions. In an active flood or emergency, consult official channels (911, local news, National Weather Service, ReadyHarris) directly. Every flood-related tool response includes a source timestamp and this same disclaimer.

Attribution & terms

• METRO: redistribution requires the legend "Route and arrival data provided by permission of METRO" to be displayed alongside any METRO-sourced output. This server adds it automatically to transit_arrivals and transit_plan responses — do not strip it in downstream use. METRO's license is limited and revocable; review https://api-portal.ridemetro.org before relying on it in anything beyond personal/hobby use.
• TranStar: usable without prior permission per their published disclaimer; review https://traffic.houstontranstar.org/api/api_doc.aspx for current terms.
• City/County open data: published for reuse; check per-dataset licenses on the portal for anything beyond typical read/analyze use.

Development

pip install -e ".[dev]"
pytest tests/                 # integration tests hit live public endpoints
ruff check src/

Roadmap

• [x] Repo scaffold, tool stubs, source client stubs
• [ ] Phase 1: CKAN + ArcGIS clients, find_dataset, query_dataset, geocode
• [ ] Phase 2: TranStar + HCFWS, flood_status, road_conditions
• [ ] Phase 3: METRO GTFS + GTFS-RT, transit_arrivals, transit_plan
• [ ] Phase 4: caching, error handling, CI, integration tests
• [ ] Phase 5: publish to PyPI and MCP registries
• [ ] Phase 6: extract city-agnostic core for other metros

Full detail in PROPOSAL.md.

License

MIT — see LICENSE. Provided as-is with no warranty; see the safety note above regarding flood and roadway data specifically.