Socrata Mcp Server

cyanheads/socrata-mcp-server

Exposes the Socrata SODA API across hundreds of government open data portals, from municipal crime stats to federal spending datasets. You get six tools covering the full workflow: list portals, search datasets by keyword or category, fetch typed column schemas, execute SoQL queries with WHERE/GROUP BY/aggregation, and optionally spill large result sets into DuckDB for analytical SQL. The schema inspection tool is critical because Socrata column types determine query syntax (bare numbers vs. quoted strings). When result sets exceed 5,000 rows, the server can register them with DataCanvas and let you run full SQL instead of paginating through SoQL. Reach for this when you need structured access to civic data without manually navigating web portals or writing raw HTTP calls.

GitHub stars: 4
tools: 6
transport: STDIO, HTTP
env vars: 10
last updated: Nov 8, 2026

View on GitHub

Install

From registry metadata

$ npx add-mcp https://socrata.caseyjhand.com/mcp --name socrata

Run in your terminal. add-mcp asks which agents to add it to (Claude Code, Codex, Cursor and more). Add -g to install it for every project.

Review the command, arguments and environment values before installing. MCP servers run with your local permissions.

Other ways

Claude Code

$ claude mcp add --transport http socrata https://socrata.caseyjhand.com/mcp

Run in your terminal. Add --scope user to make it available in every project.

Tools

Verified live · 6 tools

Verified live against the running server on Nov 6, 2026.

socrata_find_datasetsSearch for datasets across all Socrata-powered government open-data portals, or scope to one portal with the domain parameter. Returns dataset IDs, names, domains, update timestamps, and column_names — the API field names SoQL takes, not display labels. Use socrata_get_dataset...8 params

Search for datasets across all Socrata-powered government open-data portals, or scope to one portal with the domain parameter. Returns dataset IDs, names, domains, update timestamps, and column_names — the API field names SoQL takes, not display labels. Use socrata_get_dataset...

Parameters* required

categoriesarray

Filter by the portal's own categories (e.g. ["Public Safety", "Transportation"]). Requires domain: each portal assigns its own categories. Multiple values are ORed: a dataset in any listed category...

domainstring

Scope search to a single portal by bare hostname (e.g. data.seattle.gov, data.cityofnewyork.us); URL forms like https://data.seattle.gov/ are accepted and reduced to the host. Omit to search all po...

limitinteger

Number of results to return (1–10,000). One call returns at most 100 results: a larger limit is served as 100, with a notice naming the offset that continues. Default 10.default: 10

offsetinteger

Pagination offset. Default 0. Must be below 10,000: the Discovery catalog serves only the first 10,000 matches of a search.default: 0

onlystring

Filter by asset type. Omit to include all types. Usually "datasets" is what you want.one of datasets · maps · files · calendars · stories

orderstring

Sort order. Defaults to relevance. Use updated_at to surface recently-refreshed datasets.one of relevance · page_views_total · created_at · updated_at

querystring

Full-text search across dataset names and descriptions. Omit to browse without filtering.

tagsarray

Filter by the portal's own tags (e.g. ["covid19", "permits"]). Requires domain: each portal assigns its own tags. Multiple values are ORed: a dataset carrying any listed tag matches. Across portals...

socrata_get_datasetFetch full metadata and column schema for a Socrata dataset by ID. Returns field names, data types, descriptions, row count, and licensing. Always call this before writing a socrata_query_dataset — the column types determine correct WHERE clause syntax: Number columns accept b...2 params

Fetch full metadata and column schema for a Socrata dataset by ID. Returns field names, data types, descriptions, row count, and licensing. Always call this before writing a socrata_query_dataset — the column types determine correct WHERE clause syntax: Number columns accept b...

Parameters* required

dataset_id*string

Four-by-four dataset ID matching pattern like kzjm-xkqj. IDs are portal-scoped: take it from socrata_find_datasets together with that result’s domain.

domainstring

Portal the dataset lives on, as a bare hostname (e.g. data.cityofnewyork.us); URL forms like https://data.cityofnewyork.us/ are accepted and reduced to the host. Pass the domain from the same socra...

socrata_query_datasetExecute a SoQL query against any dataset on any Socrata portal. Use the search parameter for quick full-text lookup, or combine select/where/group/having/order for full analytical control. Returns rows plus the assembled SoQL string so you can learn the pattern. Columns are re...13 params

Execute a SoQL query against any dataset on any Socrata portal. Use the search parameter for quick full-text lookup, or combine select/where/group/having/order for full analytical control. Returns rows plus the assembled SoQL string so you can learn the pattern. Columns are re...

Parameters* required

canvas_idstring

Optional 10-char DataCanvas token from a prior socrata_query_dataset or socrata_dataframe_describe call. Omit on first call to mint a fresh canvas. Large result sets spill here automatically unless...

dataset_id*string

Four-by-four dataset ID (e.g. kzjm-xkqj). IDs are portal-scoped: take it from socrata_find_datasets together with that result’s domain.

domainstring

groupstring

SoQL GROUP BY clause over API field names (field_name from socrata_get_dataset). Requires an aggregate function in select.

havingstring

SoQL HAVING clause. Filters on aggregated results, e.g. count > 100.

limitinteger

Max rows to return (1–50,000). 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. Default 100. Use with off...default: 100

offsetinteger

Row offset for pagination. Default 0.default: 0

orderstring

SoQL ORDER BY clause over API field names or select aliases, e.g. "total_deaths DESC" or "date ASC".

searchstring

Full-text search across all text columns ($q). For field-specific filtering, use where instead.

selectstring

SoQL SELECT clause — API field names (field_name from socrata_get_dataset, not display labels), aliases, aggregates: "state, sum(deaths) as total_deaths". Omit for all columns.

stageboolean

Stage the matching rows on a canvas when more rows match past this page and the server has a canvas. Default true. Pass false to return the page alone, skipping the staging request; canvas_id and t...default: true

table_namestring

Name for the canvas table a spill stages: letters, digits, and underscores, starting with a letter or underscore, 63 characters at most; lowercased, and not a SQL keyword such as select or order. D...

wherestring

SoQL WHERE clause over API field names (field_name from socrata_get_dataset). Check column data_type there first — Number columns: year=2023, Text columns: year='2023'; an unquoted text value is re...

socrata_list_portalsList known Socrata-powered government open-data portals with their domain, organization name, and approximate dataset count. The catalog is a curated list of 39 well-known portals; dataset counts are fetched from the Discovery API and cached for ~24 hours. Filtering is client-...3 params

List known Socrata-powered government open-data portals with their domain, organization name, and approximate dataset count. The catalog is a curated list of 39 well-known portals; dataset counts are fetched from the Discovery API and cached for ~24 hours. Filtering is client-...

Parameters* required

limitinteger

Max portals to return (1–200). Default 50.default: 50

offsetinteger

Pagination offset. Default 0.default: 0

querystring

Keyword to filter portal names or organization names (case-insensitive substring match). Omit to list all portals.

socrata_dataframe_describeList registered tables in a DataCanvas session — schema, row count, and column names. Shows what datasets are available for SQL queries via socrata_dataframe_query. Meaningful when the server has a DataCanvas. Use after socrata_query_dataset spills a large result set to canvas.1 params

List registered tables in a DataCanvas session — schema, row count, and column names. Shows what datasets are available for SQL queries via socrata_dataframe_query. Meaningful when the server has a DataCanvas. Use after socrata_query_dataset spills a large result set to canvas.

Parameters* required

canvas_idstring

Canvas ID returned by socrata_query_dataset when a large result spills to canvas. Required in practice when canvas is enabled — canvases cannot be enumerated, so omitting it fails with canvas_id_re...

socrata_dataframe_queryRun SELECT-only SQL against a DataCanvas table populated by socrata_query_dataset. Columns SODA types as number (including aggregate aliases like count(*) as n) are staged as DOUBLE, so numeric comparisons work without a cast (year > 2020, amount < 500). Text and timestamp col...3 params

Run SELECT-only SQL against a DataCanvas table populated by socrata_query_dataset. Columns SODA types as number (including aggregate aliases like count(*) as n) are staged as DOUBLE, so numeric comparisons work without a cast (year > 2020, amount < 500). Text and timestamp col...

Parameters* required

canvas_id*string

Canvas ID returned from socrata_query_dataset or socrata_dataframe_describe.

limitinteger

Max rows to return (1–50,000). One call returns at most 10,000 rows: a larger limit is served as 10,000, with a notice naming how to page through the rest when more rows match. Default 1000.default: 1000

sql*string

SELECT-only SQL to run against registered canvas tables. DDL, DML, and file-reading functions are rejected. Use table names from socrata_dataframe_describe.

Configuration

SOCRATA_APP_TOKEN

Socrata app token (X-App-Token header). Without a token, requests share a throttled pool per source IP. Free to register at any Socrata portal.

SOCRATA_DEFAULT_DOMAINdefault: data.seattle.gov

Default portal domain when domain is omitted from tool calls (e.g. data.seattle.gov, data.cityofnewyork.us).

SOCRATA_DATAFRAME_DROP_ENABLEDdefault: false

Set to true to enable socrata_dataframe_drop, which deletes staged DataCanvas data. Off, the tool is omitted from the tool list.

SOCRATA_CLAMP_LIMITSdefault: true

Serve a limit above a tool's per-call cap at the cap, with a notice naming the offset that continues, instead of rejecting it. Set to false to restore each cap as the schema maximum.

MCP_LOG_LEVELdefault: info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_TRANSPORT_TYPEdefault: http

Selects the HTTP transport.

MCP_HTTP_HOSTdefault: 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault: 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault: /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault: none

Authentication mode to use: 'none', 'jwt', or 'oauth'.