OpenCivicQuery
You can ask plain-language questions of government open data across Socrata portals and get checkable, evidence-backed results.
Search the Socrata catalog across all portals or a specific portal, with source-pack status.
List source packs, documented portals/datasets, and when each pack was last checked.
Inspect dataset schemas, source update times, row grain, counting guidance, and caveats before querying.
Run read-only SoQL queries with row ceilings, completeness flags, warnings, methodology, source links, live query URLs, and immutable evidence snapshots.
Pin temporary snapshots indefinitely for published stories and retrieve snapshots for verification.
Query datasets without source packs too, with a ROW GRAIN UNKNOWN warning.
Use it from Claude, ChatGPT, or any MCP client, with responses governed by server-side presentation rules.
Provides an MCP integration for ChatGPT/OpenAI clients to query Socrata government open-data portals in plain language, including dataset discovery, schema inspection, read-only queries, and verifiable evidence snapshots.
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., "@OpenCivicQuery How many residential evictions were executed in New York City in 2025, by borough?"
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.
OpenCivicQuery
OpenCivicQuery is an MCP server that lets reporters ask questions of government open data in plain language, from Claude, ChatGPT, or any other MCP client. It reaches every portal on the Socrata platform: cities, counties, states, and federal agencies.
Status: early development. The interface may change.
Why the answers can be checked
Every answer that contains a number comes with:
the counting unit, so "170 eviction notices" never turns into "170 evictions";
a completeness flag, so a truncated result is never reported as a total;
the exact query and a public link that reruns it on the city's own portal;
the source's last update time;
an evidence snapshot that freezes the rows behind the figure.
These rules live in the server and travel with every response, so they hold in any client, with or without an extra skill or prompt.
Related MCP server: socrata-mcp
Source packs
Anyone can query any dataset on any Socrata portal. A source pack adds what the raw data does not say: what one row means, how to count it, and the traps. For example, the New York City pack records that restaurant inspection rows are violation citations, so counting rows overstates the number of restaurants.
Datasets without a pack still work. Their responses carry a warning that the row unit is unknown.
Which portals it reaches
Any portal the Socrata catalog lists. Dataset counts below come from the catalog on 2026-10-27 and change often.
Level | Examples (datasets) |
City | New York (2,406), Chicago (924), Austin (710), San Francisco (668), Los Angeles (361), Dallas (342), Oakland (313), Cambridge MA (281), Baton Rouge (240), New Orleans (209), Kansas City MO (198), Seattle (147), Buffalo (139), Providence (122) |
County | Cook IL (523), Montgomery MD (471), King WA (268), Santa Clara CA (131) |
State | Maryland (1,546), Washington (1,070), New York (1,035), Texas (830), Connecticut (654), Colorado (639), Oregon (539), Pennsylvania (352) |
Federal | CDC (1,084), Department of Transportation (459), HealthData.gov (147) |
Some large publishers use other platforms and are not reachable yet, including Boston, Washington DC, Philadelphia, Denver, Baltimore, San Jose, Los Angeles County, California, and Massachusetts.
Current packs: San Francisco (packs/us-ca-san-francisco.yaml) and New York City (packs/us-ny-new-york-city.yaml). To add a city, see Contributing a source pack.
Install
A public instance runs without login at https://opencivicquery-1040721507408.us-west1.run.app/mcp. The plugin connects to it and adds the Ask Open Data skill, which teaches the assistant how to turn a reporter's question into a countable one, compare periods, and hand back evidence an editor can check.
Claude: the plugin
The plugin has two parts: the skill, and a connection to the server. Claude installs the skill with the plugin, but the connection has to exist as a connector before the plugin can use it.
Add the connector. Paste the URL above as a custom connector with no authentication. On Pro and Max, open Customize, Connectors. On Team and Enterprise, an Owner adds it in Organization settings, Connectors, and each member then connects it under Customize, Connectors.
Install the plugin.
Claude desktop app (paid plans): open Customize, Plugins, Add, Add marketplace, and enter
jdzhrch/opencivicquery. Then install OpenCivicQuery.Claude Code: run
/plugin marketplace add jdzhrch/opencivicquery, then/plugin install opencivicquery@opencivicquery.Organization-wide sync: Claude's organization sync accepts only private or internal repositories, so it cannot sync this public one directly. An organization that wants central distribution can keep a private copy of this repository and sync that. Sync runs when a pull request that raises the plugin version merges into the default branch.
Claude: connection only
In Claude on the web or desktop, open Settings, Connectors, Add custom connector, and paste the URL above. The server's own rules still apply; the skill is not included.
ChatGPT
Business or Enterprise workspace: an admin creates a custom app (MCP connector) with the URL above and no authentication, and copies its app ID (
asdk_app_...). Then build the plugin package and publish it to the workspace:uv run python scripts/build_chatgpt_plugin.py --app-id asdk_app_YOUR_APP_IDThe package in
dist/holds the same skill as the Claude plugin. For a new version, rebuild and publish again; members do not reinstall.Individual accounts: add the URL as a custom connector in developer mode. The skill is not included.
The hosted instance caps each direct caller, such as Claude Code or a script, at 200 calls a day per IP address, on top of a server-wide daily cap. Claude and ChatGPT connectors reach the server from the vendors' own addresses on behalf of many users, so their calls count only toward the server-wide cap. Audit logs record a salted hash of the address, never the address itself. For heavy use, run your own copy.
Quickstart: run it on your computer
You need uv.
git clone https://github.com/jdzhrch/opencivicquery.git
cd opencivicquery
uv syncClaude Code
claude mcp add opencivicquery \
-e OPENCIVICQUERY_CONFIG_PATH="$PWD/deployments/local.yaml" \
-e OPENCIVICQUERY_TRANSPORT=stdio \
-e OPENCIVICQUERY_SNAPSHOT_PATH="$HOME/.opencivicquery/snapshots" \
-- uv --directory "$PWD" run opencivicquery-serverClaude Desktop
Add this to claude_desktop_config.json, with your own paths:
{
"mcpServers": {
"opencivicquery": {
"command": "uv",
"args": ["--directory", "/path/to/opencivicquery", "run", "opencivicquery-server"],
"env": {
"OPENCIVICQUERY_CONFIG_PATH": "/path/to/opencivicquery/deployments/local.yaml",
"OPENCIVICQUERY_TRANSPORT": "stdio",
"OPENCIVICQUERY_SNAPSHOT_PATH": "/path/to/snapshots"
}
}
}
}Then ask, for example: "How many residential evictions were executed in New York City in 2025, by borough?"
The local setup uses no login and no Socrata app token. Socrata serves token-less requests from a shared pool, which is enough for one person.
Run it as a web service
ChatGPT and hosted Claude connectors need a public HTTPS address. Run the HTTP transport:
cp .env.example .env # then edit
uv run opencivicquery-serverThe MCP endpoint is /mcp and the health check is /health. The Dockerfile builds an image for Cloud Run or any container host.
This is a query-only service. Independent GET event streams at the MCP endpoint return HTTP 405 with Allow: POST, including requests from older clients. Normal POST initialization and tool calls still work; health checks, OAuth discovery, and the local stdio transport are unchanged. The service does not provide idle change-notification subscriptions. A server that scales to zero may take longer to answer the first request after an idle period.
Configuration
A deployment file in deployments/ sets:
Setting | Meaning |
|
|
| Environment variable that holds a Socrata app token. Use one on any shared instance. |
| Calls that reach a data source or read a snapshot, per UTC day, per server process |
| Calls to one portal in any rolling minute, per server process |
| Calls one client may make per UTC day, per server process. A client is one IPv4 address or one IPv6 /64. Leave it out for a local install. |
| Required with |
| Address ranges that carry many users at once, such as hosted AI connectors. Their calls skip the per-client cap and meet only the server-wide caps. Files use the |
| Source pack files to load |
| Who may sign in, used only when login is on |
Environment variables:
Variable | Default | Meaning |
| required | Deployment file |
|
|
|
|
|
|
|
| HTTP bind address. The Docker image sets |
|
|
|
|
| Folder for local snapshots |
| Bucket for Cloud Storage snapshots |
Login is off by default. A newsroom that wants per-reporter attribution can turn on Google sign-in; see deployments/newsroom-with-login.example.yaml and the OAuth variables in .env.example. A deployment file with an access section refuses to start while login is off, so a forgotten setting never opens a private instance to everyone.
The usage caps count per process and reset when that process restarts. Concurrent instances have separate counters, and repeated restarts can reset the allowance again within the same day. The platform's instance ceiling limits concurrent capacity; it does not impose a hard daily usage or spending limit.
The per-client cap raises the cost of abuse; it does not prevent it. Someone with ten addresses, or one IPv6 block, can still use up the server process's daily allowance. Monitor actual usage and billing rather than treating these caps as a guaranteed budget.
Contributing a source pack
Pick datasets reporters ask about. Find them with the
search_datasetstool or on the portal.Check each dataset against live data before you write anything: what one row represents, whether a unique key holds, which time field to use, and which values are missing or odd.
Write the profile:
row_grain,counting_guidance, andcaveats. Every statement must come from the agency's own dataset or field description, or from a live query you ran, and nothing you inferred goes in. Put the basis in a comment beside each statement:# official: <where>or# checked <date>: <what the query showed>. A test fails when a statement has no basis. When the data contradicts the documentation, record what the query showed.Set
checked_onto the date you checked.Add the pack to a deployment file and run the tests.
Plugin development
The skill lives in plugins/opencivicquery/skills/ask-open-data/. Both the Claude plugin and the ChatGPT package use it, and the version in plugins/opencivicquery/.claude-plugin/plugin.json applies to both. Raise that version with every change to the skill or the connection.
Development
uv sync
uv run pytest
uv run ruff check src testsAfter you change dependencies, regenerate the pinned requirements:
uv export --frozen --no-dev --no-emit-project --format requirements.txt --output-file requirements.txtLicense
MIT. See LICENSE.
Available Tools
6 toolsdescribe_datasetA
Return a dataset schema, source update time, and, when a source pack documents it, the row grain, counting guidance, and caveats. Call this before writing a query.
Inputs: domain (required), dataset_id (required), reporter_question (required).
get_snapshotA
Read a temporary or pinned evidence snapshot for verification. The snapshot contains the exact query, frozen rows, source update time, completeness, methodology, and warnings.
Inputs: snapshot_uri (required).
list_source_packsA
List the portals and datasets that a source pack documents, with the date each pack was last checked against live data. Datasets outside these packs are still queryable, but their responses carry a ROW GRAIN UNKNOWN warning.
Inputs: no named parameters.
pin_snapshotA
Preserve a temporary query snapshot indefinitely for a published story. Use the snapshot URI returned by query_dataset.
Inputs: snapshot_uri (required).
query_datasetA
Run a read-only SoQL query with a mandatory row ceiling. The response on success states completeness, warnings, methodology, source update time, the public dataset page, the exact query, a public live-result query_url when the source supports one, and the URI of an immutable evidence snapshot. If completeness is truncated, revise the query or report the limitation. The response also carries presentation_rules, which govern how you must state its figures to the user; obey every rule listed there before you write your reply. Failures return isError=true and an error object with the failure code, message, argument, and http_status. A failed query has no data result or snapshot.
Inputs: domain (required), select (required), dataset_id (required), reporter_question (required), +4 more. Returns: object
search_datasetsA
Search the Socrata catalog for datasets. Leave domain empty to search every portal, or give a portal hostname to search one. Each result says whether a source pack documents it. Search results do not carry a quality, review, reliability, or publication status.
Inputs: search_term (required), reporter_question (required), limit, domain.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a distinct role across the lifecycle: discovering packs/datasets, inspecting schema, running queries, and reading or pinning snapshots. The pair pin_snapshot and get_snapshot is clearly separated by write/preserve versus read/verify semantics. Search and listing tools are differentiated by catalog search versus documented source packs.
All tool names follow a consistent snake_case verb_noun pattern (list_source_packs, search_datasets, describe_dataset, query_dataset, pin_snapshot, get_snapshot). The convention is predictable throughout.
Six tools is well scoped for a civic data query server, covering discovery, schema inspection, querying, and evidence snapshots without unnecessary surface area. Each tool clearly earns its place.
The surface covers the core workflow from dataset discovery through schema inspection, query execution, and snapshot verification/pinning. Minor gaps exist around managing pinned snapshots, such as listing or unpinning them, but these do not block the primary use case.
Maintenance
Related MCP Connectors
Connect your ads, shop, analytics, social, CRM and finance platforms once, then let Claude, ChatGPT, Cursor or any MCP client read, join and explain your numbers. Public statistics from the World Bank, IMF, Eurostat, OECD, WHO and SEC filings come as context, searchable and chartable from the same tools. Read-only by design, every number carries its source.
Query official statistics through MCP, with periods, places and citable sources in every answer.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Related MCP Servers
AlicenseAqualityDmaintenanceAn MCP server that gives Claude deep access to US public data -- demographics, economics, crime, employment, weather, housing, transit, schools, budgets, and more across 30+ cities for government intelligence workflows.28MIT- AlicenseAqualityDmaintenanceAn MCP server that gives LLM agents typed, cached access to civic open-data portals via Socrata (SODA 2.1 + Discovery API), enabling search, query, profiling, sampling, and CSV export of datasets.6MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server that connects to open data portals like CKAN and Socrata, enabling natural language querying of datasets via Claude.MIT
- AlicenseAqualityDmaintenanceAn MCP server that puts open data on tap, enabling LLM clients to search, inspect, and query 30,000+ civic datasets from Socrata portals with built-in guardrails like row caps and actionable error messages.41MIT