opendata-atlas lets an AI assistant discover, explore, and query public government open-data portals on Socrata, read-only.
Find portals by place name, alias, portal name, or host (atlas_find_portals), filtered by tier, jurisdiction level, or country.
Search a portal's datasets by topic, category, or browse most-viewed; includes match evidence and flags non-queryable external assets (atlas_search_datasets).
Describe a dataset: columns, types, live row count, time coverage, place fields, geo columns, knowledge level, and sample rows (atlas_describe_dataset).
Query a dataset with SoQL: read records (paged, capped at 10,000 rows) or compute counts, sums, groupings, and other aggregates; supports filters, ordering, full-text search, and radius (near) geo filters (atlas_query_dataset).
Read built-in reference help: capabilities, portals, dataset guides, SoQL syntax, error catalog, and contribution/tier definitions (atlas_get_reference), also exposed as MCP resources.
Read-only and safe: never modifies data; results include caveats and knowledge notices when data lacks reviewed documentation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@opendata-atlas How many bikes crossed Seattle's Fremont Bridge this month?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Let your AI assistant answer questions with public government data. opendata-atlas connects an assistant such as Claude or Codex to the open-data portals that cities, counties, states and other public agencies publish on Socrata. Your assistant can find the right portal and dataset, check what its columns mean, and answer with counts, trends and records drawn from the data itself.
It is an MCP server, the standard way to give AI assistants new tools. It only reads public data and never changes anything on a portal.
Status: preview. Version 0.3.0 is on PyPI and in GitHub Releases. Your assistant can search every portal in the server's registry of public Socrata portals. Six portals are curated: Seattle (seattle), Chicago (chicago), City of Everett (everett), King County (king-county), NYC Open Data (data.cityofnewyork.us) and Los Angeles (los-angeles).
Once the server is connected, ask your assistant questions like these:
"Where can I find Seattle's real-time fire 911 call data, and how current is it?"
"How many bikes have crossed the Fremont Bridge this month?"
"How many crimes were reported in Chicago's Hyde Park community area last month?"
"Show me recent restaurant health inspection results for Everett, WA."
"How many jail bookings were there in King County last month?"
Answers come from the live portal, so they change as the data does.
Related MCP server: mcp-data-connecticut
You need an MCP client that can start a local server, such as Claude Desktop, Claude Code or Codex. The uvx commands below also need uv; the server runs on Python 3.13 or later, which uv installs for you if needed. No account or API key is required.
Claude Desktop: download opendata-atlas-<version>.mcpb from the latest release and open it with Claude Desktop.
Claude Code, as a plugin:
claude plugin marketplace add briandconnelly/opendata-atlas
claude plugin install opendata-atlas@opendata-atlasCodex, as a plugin:
codex plugin marketplace add briandconnelly/opendata-atlas
codex plugin add opendata-atlas@opendata-atlasThe plugin adds the server, pinned to the latest release, and the curate-portal skill, which contributors use in a clone of this repository to add a portal (CONTRIBUTING-portals.md). The skill follows the clone's own skills/curate-portal/SKILL.md, so a run uses the instructions you have checked out, and does nothing outside a clone. Codex starts it only when you name it ($curate-portal). To pick up a new release, run claude plugin update opendata-atlas@opendata-atlas or codex plugin marketplace upgrade opendata-atlas.
To add only the server instead, in Claude Code:
claude mcp add opendata-atlas -- uvx opendata-atlasThis makes the server available to you in the current project. To use it in every project, add --scope user after add. In Codex:
codex mcp add opendata-atlas -- uvx opendata-atlasAny other MCP client: run uvx opendata-atlas as a stdio server. Most clients take an entry like this in their configuration file:
{
"mcpServers": {
"opendata-atlas": { "command": "uvx", "args": ["opendata-atlas"] }
}
}To set up Claude Desktop this way instead of with the bundle, merge the opendata-atlas entry into mcpServers in claude_desktop_config.json (on macOS, ~/Library/Application Support/Claude/claude_desktop_config.json), then restart Claude Desktop. If it cannot find uvx, set command to the absolute path that which uvx prints.
To check the connection, ask your assistant "Which open-data portals can you search for Seattle?"
Finding a portal. Name the place you mean, and your assistant looks up its portal. When a place has more than one, such as a city and its county, the assistant asks which you mean unless your question already says. Each portal also has an id (its hostname, such as data.seattle.gov), and many have a short alias (such as seattle).
Curated portals. Every registered portal can be searched and queried. On a curated portal, contributors have also reviewed key datasets: what one row stands for, which columns hold places, and which time column to count by. Most portals have no such review, and even on a curated one, many datasets don't.
Knowledge levels. For each dataset, the server tells your assistant how much reviewed knowledge it has (reviewed, profiled or none). When a question depends on a column nobody has reviewed, or on a review that has gone stale, the result carries a caveat that your assistant should pass on to you. CONTRIBUTING-portals.md defines the levels exactly.
Public Socrata data only. The server reads public datasets on portals in its registry. It cannot read private datasets or query other platforms. ArcGIS layers listed in a portal's catalog show up in search, but cannot be queried.
Bounded reads. A query returns records a page at a time, and at most 10,000 rows in total. Counts, sums and other summaries can still cover a whole dataset of any size.
No geocoding or forecasting. The server cannot turn an address into coordinates, and it reports what the data says rather than predicting.
Data quality is the publisher's. Coverage, freshness and accuracy vary by portal and dataset.
No configuration is required. Two optional environment variables change the defaults:
SOCRATA_APP_TOKEN: a Socrata application token, for example claude mcp add opendata-atlas -e SOCRATA_APP_TOKEN=... -- uvx opendata-atlas. The bundle asks for it in Claude Desktop's settings. The Claude Code plugin passes SOCRATA_APP_TOKEN and OPENDATA_ATLAS_PORTALS through from the environment Claude Code starts in; the Codex plugin passes neither. To set them in Codex, remove the plugin first (codex plugin remove opendata-atlas@opendata-atlas), then add the server with codex mcp add opendata-atlas -e SOCRATA_APP_TOKEN=... -- uvx opendata-atlas; with both installed, the plugin's server keeps running with no token and no allowlist. If a portal rejects the token, the server reports app_token_rejected rather than silently dropping it. A token may not be accepted by every portal.
OPENDATA_ATLAS_PORTALS: limits the server to the portals you list, by id or alias, separated by commas (for example, seattle,chicago). Any other portal fails with portal_not_enabled. Names that match no portal are ignored, so a list in which nothing matches blocks every portal. Unset or blank, every registered portal is served.
The server gives your assistant five tools:
Tool | Purpose |
| Find portals by place name, alias, portal name or host |
| Find a portal's datasets by topic |
| A dataset's columns, row count, time coverage, place and map columns, and knowledge level |
| Read records or compute summaries, in SoQL, Socrata's SQL-like query language |
| Built-in help: capability summary, SoQL help, portals, guides, error catalog |
The same reference material is also served as MCP resources, for clients that browse them:
Resource | Contents |
| Index of the reference topics |
| Capability summary: what the server does and does not do, rules, semantics, failures |
| Curated and profiled portals ( |
| One portal: identity, tier, knowledge by dataset, guide index |
| A portal's guides, and one guide |
| SoQL reference: syntax, filtering, aggregation, dates, geography, paging |
| Error catalog |
| Tier, knowledge-level and validation definitions, and how to contribute portal knowledge |
The {portal}, {section_id} and {guide_id} parameters support completion.
Bugs and questions: open an issue at github.com/briandconnelly/opendata-atlas/issues.
A portal is missing: open an issue with the portal's address. To add it yourself, add an entry to registry_overrides.toml (its comments and docs/design.md describe the fields) and open a pull request; scripts/build_registry.py checks that the portal is eligible and its identity holds.
Portal knowledge: CONTRIBUTING-portals.md describes how to review a portal's datasets.
Code: CONTRIBUTING.md covers running from source and the test suite. Maintainers release with docs/releasing.md.
The rest of the documentation lives in docs/; there is no hosted docs site.
Decide whether and how to query a dataset: columns, live row count, data_coverage
(actual time range), place fields for "in " questions (with reliability),
and geo columns for near.
Call before querying a dataset whose columns you do not know.
For area questions, use detail="full".
Filter a place field on its value, never its label; an area may span several values.
Illustrative example: {"portal": "example-city", "dataset_id": "abcd-1234", "detail": "full"}.
With column_cursor, send only portal, dataset_id, column_query, detail, column_cursor.
Typically 1-3 s; fails with query_timeout after 30 s.
Inputs: portal (required), dataset_id (required), detail, sample_rows, +2 more. Returns: title, source, columns, guide_uri, +16 more
Find portals by place name; the portal id it returns goes in every other tool's portal.
Call this before any tool that takes portal when you lack its id.
It never picks a portal for you: an ambiguous place returns every candidate, told apart
by jurisdiction.level (a city portal and its county portal can both match).
When candidates differ in jurisdiction.level, ask the user which they mean, unless the
request already says.
Candidates are ordered by match (alias, name, place_name, host), then tier, then id.
No match is an empty candidates list, not an error.
With cursor, send only cursor and optionally page_size.
Example: {"query": "Chicago"}. Reads the shipped registry; no network call.
Inputs: tier, level, query, cursor, +2 more. Returns: source, has_more, candidates, next_cursor, +1 more
Read the server's reference: capability summary, portals, dataset guides, SoQL help, error catalog, and tier definitions. Call with no arguments for the index.
If your client did not show you the server instructions, read topic capabilities before your first query. Example: {"topic": "soql", "item_id": "dates"}. With cursor, repeat only topic and, for guides, portal.
Inputs: topic, cursor, portal, item_id. Returns: uri, body, title, topic, +6 more
Run a bounded read or aggregate on one dataset; paging stops at 10,000 rows.
For counts and breakdowns, use count() with group_by, not row paging. With cursor, send only portal, dataset_id, cursor, and optionally page_size or detail. For all rows, give the user download_url (clauses mode, detail="full") instead of paging. Honor coverage_warnings and knowledge_notice in the answer; take relative dates from source.now_local. Illustrative example: {"portal": "example-city", "dataset_id": "abcd-1234", "select": ["type", "count() AS n"], "group_by": ["type"], "order_by": ["n DESC"]}. Typically 1-5 s; fails with query_timeout after 30 s.
Inputs: portal (required), dataset_id (required), mode, near, +10 more. Returns: rows, hints, source, columns, +15 more
Find a portal's datasets by topic. Call when you lack a dataset id.
Results are candidates: match_evidence lists the query words each one's metadata lacks. Only queryability "supported" can be described or queried; a tabular search also returns up to 3 external_matches, which cannot. Illustrative example: {"portal": "example-city", "query": "fire 911"}. Typically 1-3 s.
Inputs: portal (required), query, cursor, detail, +3 more. Returns: source, datasets, has_more, truncated, +7 more
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 5 tools
Each tool occupies a distinct stage of a clear pipeline: find a portal, search its datasets, describe a dataset's schema, query it, and read static reference material. Descriptions explicitly state prerequisites and hand-offs (portal id, dataset_id), so an agent can sequence them without confusion. No two tools overlap in purpose.
All five tools share the `atlas_` prefix and a consistent verb_noun pattern (find_portals, search_datasets, describe_dataset, query_dataset, get_reference). The singular/plural noun choice matches cardinality sensibly (portals/datasets vs. dataset).
Five tools is on the lean side but each maps to a necessary step in an open-data discovery-to-query workflow, with no filler. A slightly larger surface (e.g. a dedicated portal listing) might be warranted, but nothing feels padded.
The surface covers the full read-only lifecycle: portal discovery, dataset search, schema/coverage inspection, bounded querying with paging and external download pointers, plus a reference/help endpoint for error catalog and SoQL guidance. Only minor gaps remain (e.g. no explicit bulk export tool, instead delegating to download_url).
Search and query government open-data portals (Socrata SODA API).
Search 77k public-sector open data APIs across 10 countries. Read-only, no API key.
Provides access to Civic Plus - See Click Fix, allowing you to interact with your data via an LLM.…
Search and call 422 official public-data APIs: elections, courts, permits, SEC filings.