Socrata MCP Server

@cyanheads/socrata-mcp-server Search and query government open-data portals (Socrata SODA API) via MCP. STDIO or Streamable HTTP. 7 Tools • 2 Data Resources • 1 Prompt • 1 Skill

Public Hosted Server: https://socrata.caseyjhand.com/mcp

Overview

Query city, county, state, and federal open-data portals built on Socrata. Discover portals and datasets, inspect column schemas, and run SoQL queries, or SQL over large result sets.

Tools

Resources

All resource data is also reachable via tools. Use the corresponding tool for agent workflows — resources are for clients that support URI-addressable data.

Prompts

Agent skill

socrata-guide covers dataset coverage checks, SoQL and DuckDB query syntax, and comparisons across staged tables. It ships with plugin installs, npm, Docker, and the MCPB bundle, and is available over MCP as skill://socrata-guide/SKILL.md.

Capability reference

socrata_list_portals tool

• Curated catalog of 39 well-known city, county, state, and federal portals — every member verified live in the Discovery catalog
• Per-portal dataset counts fetched live from the Discovery API, cached ~24 hours (0 means the portal exposes no dataset assets to the catalog; null means the count is temporarily unavailable)
• Client-side substring filtering on domain or organization name; pagination up to 200 per page with offset
• Returns domain (pass to socrata_find_datasets), organization name, and approximate dataset count; the count includes datasets a portal federates from another Socrata tenant (Austin, Illinois, Mesa, and San Francisco publish through a data hub; Seattle catalogs under a sibling tenant)
• Never fails on an upstream error — a count that cannot be fetched, or that the call's 50-second deadline cuts off, keeps its last known value, or comes back null when it has none, and the listing still returns
• Past-the-end notice: an empty page at offset > 0 names the offset to page below

socrata_find_datasets tool

• Full-text query across dataset names/descriptions; scope with domain, filter by the portal's own categories/tags (several values of one filter are ORed), restrict only to an asset type (datasets, maps, files, calendars, stories)
• categories and tags require domain: each portal assigns its own, and without one Discovery matches them against a Socrata-wide taxonomy the results never report. Either without domain fails domain_required before any request; search across portals with query. An empty array or a blank entry reads as unset
• Sort by relevance, page views, created date, or updated date; limit up to 10,000 with SOCRATA_CLAMP_LIMITS on, served 100 per call with a notice naming the offset that continues (the schema maximum is 100 with it off)
• Discovery serves only the first 10,000 matches of a search: offset must stay below 10,000, and totalCount stops at 10,000 with totalCountCapped: true marking that figure a lower bound
• Returns dataset IDs, names, domains, tags, update timestamps, and column_names — the API field names SoQL takes (cuisine_description, not the display label CUISINE DESCRIPTION), computed-region columns dropped — call socrata_get_dataset for typed schema before writing queries
• Each result carries asset_type (dataset, filter, map, chart, story, href, …; only dataset and filter answer socrata_query_dataset with rows) and parent_dataset_ids, the assets a filter, map, chart, or story is built from (dfnk-7re6, Chicago's crimes map → x2n5-8w5q); each is absent when the catalog lists none
• Recovery hints on empty results — echoes applied filters and suggests how to broaden; a page past the last match says so and names the offset to page below. The notice also covers a limit served below the one requested
• domain takes a bare hostname; URL forms (https://data.cdc.gov/) are reduced to the host. A scoped search covers every dataset the portal publishes, including ones federated from another Socrata tenant, reported under the portal's own domain
• Typed errors: domain_required when categories or tags arrive without domain, result_window_exceeded when offset is 10,000 or more, rate_limited (retryable) when the Discovery API returns 429, retry_deadline_exceeded (retryable) when the call passes its 50-second deadline, unknown_domain when the Discovery catalog does not index the domain, invalid_domain when the domain is not a hostname

socrata_get_dataset tool

• Returns field names, Socrata data types, descriptions, row count (with row_count_source provenance), licensing, and asset_type (dataset, filter, map, …) when available; only dataset and filter answer socrata_query_dataset with rows
• Column data_type determines WHERE clause syntax: Number → bare literals (year=2023), Text → single-quoted strings (year='2023')
• Excludes computed region columns (:@computed_region_*) to reduce noise; includes per-column non-null counts when available
• Dataset IDs are portal-scoped — pass the domain from the same socrata_find_datasets result; URL-form domains are reduced to the host. dataset_id takes either letter case and is sent lowercased; a malformed ID fails argument validation before any request
• Typed errors: not_found (no such dataset on the domain queried — the message names the ID and domain, and the recovery names the portal that holds the ID when the Discovery catalog knows it), unknown_domain (the domain is not serving the Socrata API — it does not resolve, is not a Socrata portal, or redirects elsewhere; fails on the first attempt), invalid_domain (not a hostname), rate_limited (retryable; honors the upstream Retry-After), retry_deadline_exceeded (retryable; the call passed its 50-second deadline)
• Always call before writing a socrata_query_dataset WHERE clause

socrata_query_dataset tool

• search for quick full-text lookup ($q), or combine select/where/group/having/order for full analytical control — clauses reference columns by API field name (field_name from socrata_get_dataset), never the display label; operators =, !=, >, <, LIKE, IN(...), BETWEEN, IS NULL, starts_with(), contains(), AND, OR, NOT
• Aggregation via count(*), sum(), avg(), min(), max() with group/having
• not_tabular identifies assets without queryable rows: SODA refuses row access (stories, measures, files, external links), or answers with no fields (maps, charts, calendars, visualizations), which fails before any recount or staging. For the second kind the recovery names the tables the asset is built on (a7mk-8suc is a map built on t6tk-mr48; query that dataset_id on data.nj.gov.), with asset_type and parent_dataset_ids in the error data; without a listed parent, search with only: "datasets". query_rejected identifies a gateway refusal of query clauses when a bare row request succeeds; simplify the query and use SoQL case(condition, value, true, fallback) for conditional aggregates.
• limit up to 50,000 with SOCRATA_CLAMP_LIMITS on, but one call returns at most 5,000 rows: a larger limit is served as 5,000, with a notice naming the offset that continues when more rows match (off, the schema maximum is 5,000). Page with offset
• total_count counts the query as written — groups for a grouped query, distinct values for a distinct select — through a bounded SoQL $query pipe recount. It is present when the match holds more rows than the response, and absent when the response holds the whole match or when the recount failed or ran past 15 seconds. truncated is set only when total_count exceeds offset + row_count, or when the page fills limit and no count exists
• An empty page at offset > 0 gets a past-the-end notice naming the match size, or a may-be-past-the-end notice when the count failed
• assembled_query echoes the SoQL string for learning the syntax; all SODA 2.1 row values are strings except geo/location columns, which return nested objects
• When the server has a canvas and more rows match past the page, up to 50,000 matching rows spill to a DataCanvas table whatever the limit (canvas_id, table_name, canvas_row_count) — list its columns with socrata_dataframe_describe, then run SQL with socrata_dataframe_query