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.

Related MCP server: TAK Server MCP

Data sources

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

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

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