Tools

Six tools covering the full Socrata workflow — portal discovery, dataset search, schema inspection, SoQL querying, and DuckDB-powered analytical SQL over large result sets:

socrata_list_portals

List known Socrata-powered government open-data portals.

• Curated catalog of 40 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 — approximate, point-in-time (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
• Use this first when you don't know which portal to target

socrata_find_datasets

Search for datasets across all Socrata portals or scope to a single portal.

• Full-text search across dataset names and descriptions
• Scope to a single portal with the domain parameter
• Filter by category (e.g. ["Public Safety", "Transportation"]) and tags (e.g. ["covid19"])
• Asset type filtering: datasets, maps, files, calendars, stories
• Sort by relevance, page views, created date, or updated date
• Pagination (up to 100 per page) with offset
• Returns dataset IDs, names, abbreviated column previews, domains, and update timestamps
• Column names here are preview-only — call socrata_get_dataset for typed schema before writing queries
• Recovery hints on empty results — echoes applied filters and suggests how to broaden

socrata_get_dataset

Fetch full metadata and column schema for a Socrata dataset by ID.

• Returns field names, Socrata data types, descriptions, row count, and licensing
• Column data_type determines correct WHERE clause syntax: Number → bare literals (year=2023), Text → single-quoted strings (year='2023')
• Excludes computed region columns (:@computed_region_*) to reduce noise
• Per-column non-null row counts when available
• Always call this before writing a socrata_query_dataset query

socrata_query_dataset

Execute a SoQL query against any dataset on any Socrata portal.

• search parameter for quick full-text lookup across all text columns ($q)
• select, where, group, having, order for full analytical control
• SoQL operators: =, !=, >, <, LIKE, IN(...), BETWEEN, IS NULL, starts_with(), contains(), AND, OR, NOT
• Aggregation: count(*), sum(), avg(), min(), max() with group and having
• Pagination up to 5000 rows per call with offset; total_count returned when result is truncated
• assembled_query in the response echoes the SoQL string for learning the syntax
• All SODA 2.1 row values are strings — geo/location columns return nested objects
• When CANVAS_PROVIDER_TYPE=duckdb and result hits the limit, rows spill to a DataCanvas table for SQL-based analysis

socrata_dataframe_describe

List registered tables in a DataCanvas session.

• Shows table name, row count, and DuckDB-inferred column types for each registered table
• Only meaningful when CANVAS_PROVIDER_TYPE=duckdb is set
• Use after socrata_query_dataset spills a large result set
• Returns canvas ID for use in socrata_dataframe_query

socrata_dataframe_query

Run SELECT-only SQL against DataCanvas tables populated by socrata_query_dataset.

• DuckDB infers types from spilled data — numeric columns that SODA returned as strings become queryable with numeric comparisons (year > 2020, amount < 500)
• SELECT-only enforcement: DDL, DML, and file-reading functions (read_csv, read_parquet) are rejected
• Up to 10,000 rows per call
• Works out of the box when CANVAS_PROVIDER_TYPE=duckdb is set — DuckDB ships as a regular dependency

Resources and prompts

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

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Pluggable auth: none, jwt, oauth
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports
• Optional DataCanvas (DuckDB, bundled) for analytical SQL over large result sets

Socrata-specific:

• Full Socrata SODA 2.1 API integration — SoQL query builder with select, where, group, having, order, search, limit, offset
• Discovery API for cross-portal dataset search and per-portal dataset counts (curated 40-portal catalog, counts cached ~24h)
• App token support (SOCRATA_APP_TOKEN) for higher per-IP rate limits
• Configurable default portal domain via SOCRATA_DEFAULT_DOMAIN
• Computed region column filtering to reduce noise in wide datasets
• DataCanvas spillover — large query results automatically register as DuckDB tables for SQL analysis

Agent-friendly output:

• Assembled SoQL string echoed in every socrata_query_dataset response so agents can learn and refine syntax
• Recovery hints on empty results — echoes applied filters with specific suggestions for broadening
• Column type context embedded in schema output with WHERE-clause quoting rules stated explicitly
• Per-item structured error reasons (invalid_id, not_found, soql_error, rate_limited) with actionable recovery text

Getting started

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "socrata-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/socrata-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):