socrata-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| SOCRATA_APP_TOKEN | No | Sent as X-App-Token; raises portal rate limits. | |
| SOCRATA_MCP_TIMEOUT | No | Per-request timeout in seconds. | 30 |
| SOCRATA_MCP_MAX_ROWS | No | Hard row cap for inline query results. | 5000 |
| SOCRATA_MCP_CACHE_DIR | No | Disk cache root. | ~/.socrata-mcp/cache |
| SOCRATA_MCP_PAGE_SIZE | No | Rows fetched per HTTP request. | 1000 |
| SOCRATA_MCP_QUERY_TTL | No | Seconds to cache query/profile results (0 disables). | 3600 |
| SOCRATA_MCP_CATALOG_TTL | No | Seconds to cache catalog searches. | 300 |
| SOCRATA_MCP_METADATA_TTL | No | Seconds to cache dataset metadata. | 300 |
| SOCRATA_MCP_DEFAULT_LIMIT | No | Rows returned when a query gives no limit. | 100 |
| SOCRATA_MCP_MAX_EXPORT_ROWS | No | Hard row cap for CSV exports. | 1000000 |
| SOCRATA_MCP_THROTTLE_INTERVAL | No | Minimum seconds between portal requests. | 0.2 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| search_datasetsA | Search open-data catalogs for datasets (Socrata Discovery API). Args: query: Full-text search, e.g. "crime reports" or "building permits". domain: Restrict to one portal, e.g. "data.seattle.gov". category: Portal category, e.g. "Public Safety". limit: Max results (default 20, cap 100). offset: Pagination offset into the result set. Returns: {results: [{id, name, domain, description, updated_at, category, permalink}], count, total, offset}. Use each result's domain + id with the other tools. |
| get_datasetA | Dataset metadata: columns with types, row count, update cadence, license. Args: domain: Portal hostname, e.g. "data.seattle.gov". dataset_id: Socrata 4x4 id, e.g. "tazs-3rd5". Returns: {name, description, columns: [{field_name, name, type, description}], row_count, license, attribution, created_at, data_updated_at, update_frequency, tags, source_url}. Use columns' field_name values in query/profile calls. |
| queryA | Query a dataset with structured SoQL parameters OR one raw SoQL string. Structured mode (recommended): pass any of select/where/group/order/
limit/offset plus optional geo filters. Raw mode: pass Args: domain: Portal hostname, e.g. "data.seattle.gov". dataset_id: Socrata 4x4 id, e.g. "tazs-3rd5". select: Columns/expressions, e.g. ["offense", "count(*) as n"]. where: SoQL filter, e.g. "offense_date > '2026-06-01T00:00:00'". group: GROUP BY columns (pair with aggregate select expressions). order: e.g. "offense_date DESC". Defaults to ":id" for stable paging. limit: Max rows returned (default 100, hard cap applies). offset: Row offset for pagination. soql: Raw SoQL query — mutually exclusive with all structured params. within_circle: {field, lat, lon, radius_m} geo filter on a point column. within_box: {field, nw_lat, nw_lon, se_lat, se_lon} geo filter. Returns:
{rows, row_count, truncated, query: {params, effective_limit, clamped}}.
|
| profile_datasetA | Profile every column: null rate, distinct count, min/max, top values. Computed portal-side via aggregate SoQL — the dataset is never downloaded. Dates and numbers get min/max (numbers also avg); low-cardinality text columns get their top 10 values with counts. Args: domain: Portal hostname, e.g. "data.seattle.gov". dataset_id: Socrata 4x4 id, e.g. "tazs-3rd5". Returns: {row_count, columns: [{field_name, type, null_rate, non_null_count, distinct_count, min?, max?, avg?, top_values?, error?}], notes}. |
| sampleA | Fetch the first n rows of a dataset (n capped at 100). Args: domain: Portal hostname, e.g. "data.seattle.gov". dataset_id: Socrata 4x4 id, e.g. "tazs-3rd5". n: Number of rows (default 10, max 100). Returns: {rows, row_count, note}. Rows are in :id order — a peek at real values, not a random sample. |
| export_csvA | Export query results to a Tableau-ready CSV via streamed, paged download. Accepts the same query parameters as Args:
domain: Portal hostname, e.g. "data.seattle.gov".
dataset_id: Socrata 4x4 id, e.g. "tazs-3rd5".
out_path: Destination .csv path (parent directories are created).
select/where/group/order/limit/soql/within_circle/within_box: as in Returns: {path, rows_written, truncated, columns, notes}. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 6 tools
Each tool targets a distinct operation: search_datasets for discovery, get_dataset for metadata, profile_dataset for column profiling, query for flexible querying, sample for quick peeks, and export_csv for bulk download. No functional overlap.
Most tools follow verb_noun pattern (export_csv, get_dataset, profile_dataset, search_datasets). 'query' and 'sample' are single verbs but remain clear and consistent with the style; minor deviation from the full pattern.
6 tools is well-scoped for a read-only Socrata data exploration server. Each tool addresses a distinct need without bloat, and the count feels appropriate for the domain.
The tool surface covers the full lifecycle of data exploration: search for datasets, inspect metadata, profile columns, query data, sample rows, and export. No obvious gaps for the intended purpose of querying and exporting open data.