# Houston METRO MCP

A local Model Context Protocol server for Houston METRO routes, stops, realtime arrivals, and service alerts.

The MCP runs on your computer through stdio. Your AI client starts it when needed, and your METRO API key is used directly by the local process—there is no hosted MCP service in between.

## Available tools

- `search_routes` — find routes by number or name
- `search_stops` — find stops by code or name
- `find_nearby_stops` — find stops closest to a latitude and longitude
- `get_next_arrivals` — get realtime arrivals for a stop, optionally filtered by route
- `get_service_alerts` — get current system-wide or route-specific alerts

The server also exposes route, stop, and data-source resources under the `metro://` URI scheme.

## Requirements

- Node.js 22 or newer
- pnpm 11
- A Houston METRO GTFS API subscription key from the [METRO Transit Data portal](https://api-portal.ridemetro.org/)

## Install

After cloning this repository, open a terminal in the repository and run:

```powershell
pnpm install
pnpm build
```

The local MCP entry point is:

```text
apps/cli/dist/index.js
```

Use its absolute path in your MCP client configuration.

## Claude Desktop

Add the server to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "houston-metro": {
      "command": "node",
      "args": ["C:/absolute/path/to/metro-mcp/apps/cli/dist/index.js"],
      "env": {
        "METRO_GTFS_API_KEY": "YOUR_METRO_API_KEY"
      }
    }
  }
}
```

Restart Claude Desktop after saving the configuration.

## Cursor

Create `.cursor/mcp.json` in the cloned repository. Cursor can resolve the repository path and API key from its supported configuration variables:

```json
{
  "mcpServers": {
    "houston-metro": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/apps/cli/dist/index.js"],
      "env": {
        "METRO_GTFS_API_KEY": "${env:METRO_GTFS_API_KEY}"
      }
    }
  }
}
```

Set `METRO_GTFS_API_KEY` in your environment, then enable the server in Cursor’s MCP settings.

## First use

The first route or stop request downloads METRO’s official Static GTFS archive and stores it in a local cache. Later sessions reuse that cache. A long-running session refreshes an expired catalog in the background and continues serving the last valid catalog if the refresh fails. Realtime arrival and alert requests use your API key and share a 15-second feed cache within the running process.

Arrival results include only stop updates with an absolute arrival or departure time. METRO updates containing only a delay cannot be converted to a predicted time until scheduled stop times are available. Route-specific alert matching uses the route name when METRO's alert IDs differ from Static GTFS route IDs.

You do not need to start a website, Worker, database, or separate background service. Your MCP client launches and stops the local process automatically.

## Troubleshooting

- Use an absolute path to `apps/cli/dist/index.js`.
- Run `pnpm build` again after pulling updates.
- Confirm `node --version` reports Node 22 or newer.
- Restart the MCP client after changing its configuration.
- Confirm your METRO subscription key is active if realtime tools return a configuration or upstream error.

## Attribution

Transit data is provided by the Metropolitan Transit Authority of Harris County, Texas (METRO). METRO trademarks and service marks remain the property of METRO. This independent project is not an official METRO product.

## License

MIT