Houston Open Data MCP

An MCP server that lets an AI assistant search and read public data from the City of Houston Open Data portal, which runs on CKAN.

Built from the GSA MCP hackathon template as a Dataset Access Server. It is read-only, and it needs no key or sign-in.

Hackathon prototype. Not an official City of Houston service.

Tools

The server also offers two prompts (explore_houston_topic, compare_by_geography) and two resources (houston://info/server, houston://docs/join-keys).

Related MCP server: Calgary Open Data MCP Server

Run it on your computer

Install uv, then, in PowerShell or any terminal:

uv sync --group dev
uv run pytest tests/ -v
uv run streamlit run streamlit_app.py

The page opens at http://localhost:8501 and the MCP endpoint is http://localhost:8501/api/mcp. Check the endpoint from a second terminal:

uv run python scripts/smoke_test.py http://localhost:8501/api/mcp

To run it as a local stdio server for Claude Code instead, use uv run python main.py.

Chat agent

The page's Ask tab is a chat agent that uses Claude and the same read-only tools. It needs ANTHROPIC_API_KEY and APP_PASSWORD, set as Streamlit secrets or locally in .streamlit/secrets.toml, which Git ignores. Copy .streamlit/secrets.toml.example to start. API usage is billed separately from a Claude plan.

Host it

See deploy/streamlit/README.md. One process serves the Streamlit page at / and MCP at /api/mcp. The template's IBM, Databricks, and cloud.gov kits in deploy/ also still work, and serve MCP alone at /mcp.

Repo layout

streamlit_app.py            # Streamlit host: page + /api/mcp
Dockerfile.streamlit        # Same host, in a container
main.py                     # Local stdio entry point
src/houston_opendata/
├── app.py                  # Builds FastMCP, picks the transport
├── portal.py               # Read-only CKAN client, shared by the tools and the page
├── page.py                 # Streamlit page
├── config.py, models.py, utils.py, routes.py
├── tools/                  # One file per tool
├── prompts/
└── resources/
scripts/smoke_test.py       # Checks a running server with a real MCP client
tests/                      # Tests that run without network access
eval/EVALUATION.md          # Evaluation write-up for the hackathon submission
deploy/                     # Deployment kits

Add a tool

Create src/houston_opendata/tools/my_tool.py with a register(mcp) function, then call it from tools/__init__.py. Put any portal call in portal.py.

Security

• Tools use only allow-listed CKAN read actions. There is no SQL endpoint and no write action.

• The portal address comes from server configuration, never from a tool argument.

• Identifiers are validated before any request, and upstream errors are sanitized.

• The endpoint has no authentication, which suits public data. Review your agency's requirements before using it beyond the hackathon.

License

MIT. See SECURITY.md.