seattle-open-data

An agent-friendly MCP server for Seattle Open Data (Socrata SODA2).

Status: alpha (0.2.0). All four tools work against the live portal, with curated guides for seven flagship datasets. See evals/results for the agent evaluation.

Tools

Install

The server runs over stdio. The uvx commands below need uv.

Claude Desktop: download seattle-open-data-<version>.mcpb from the latest release and open it with Claude Desktop.

Claude Code:

claude mcp add seattle-open-data -- uvx seattle-open-data

Codex:

codex mcp add seattle-open-data -- uvx seattle-open-data

Any other MCP client: run uvx seattle-open-data as a stdio server:

{
  "mcpServers": {
    "seattle-open-data": { "command": "uvx", "args": ["seattle-open-data"] }
  }
}

Optional app token: set SOCRATA_APP_TOKEN to use a Socrata application token, for example claude mcp add seattle-open-data -e SOCRATA_APP_TOKEN=... -- uvx seattle-open-data. The bundle asks for it in Claude Desktop's settings. A rejected token is reported as app_token_rejected, never silently dropped.

Develop

From a checkout:

uv sync
uv run seattle-open-data                                  # run the server over stdio
uv run pytest
uv run ruff check && uv run ruff format --check && uv run ty check
UPDATE_SNAPSHOTS=1 uv run pytest tests/test_contract.py   # after an intended tool-surface change
uv run pytest --run-integration -m integration            # live tests against data.seattle.gov
uv run python evals/run.py [--host claude|codex] <out_dir> [task_id ...]
uv run python evals/report.py <out_dir> --answers

To build the MCPB bundle locally (needs the mcpb CLI): make mcpb.

Release

Tag vX.Y.Z after bumping the version: the release workflow builds and smoke-tests the wheel, sdist, and .mcpb, publishes to PyPI after maintainer approval, and attaches all three to a GitHub Release. See docs/releasing.md for the steps, the TestPyPI rehearsal, and one-time setup.

License

MIT