Commonwealth-MCP
Commonwealth-MCP provides read-only Virginia civic and geographic lookup tools with provenance, coverage, and warnings.
Resolve a Virginia jurisdiction from a name/alias/FIPS code or lon/lat point, including independent cities, towns, layered authorities, and ambiguous candidates.
Find parcel records by parcel PIN or lon/lat within a jurisdiction; no street-address geocoding yet.
Find zoning districts for a parcel PIN or point; results are screening-only GIS answers, not legal determinations.
Retrieve jurisdiction boundary metadata and optional full geometry; boundary geometry is generalized screening geometry only.
Look up a Code of Virginia section by exact citation; it is not a full-text search, and missing/repealed sections return
found=False.Return structured evidence, source provenance, coverage dimensions, failures, warnings, and user-choice requirements when matches are ambiguous.
Provides access to Virginia state and local government geographic data through ArcGIS services, including parcel, zoning, and boundary lookups with source provenance.
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., "@Commonwealth-MCP What zoning applies to parcel 0102 14 0231 in Fairfax County?"
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.
Commonwealth-MCP
Python tools for Virginia public data, with a command-line interface and an MCP server for AI assistants. For policy researchers and developers building applications for Virginia residents.
Try the browser demos · Search the tools · Run examples · Add a data source · Design and remaining work
Independent project. Not affiliated with or maintained by the Commonwealth of Virginia.
Start here
MCP (Model Context Protocol) lets an AI client call functions supplied by a server. Here, those functions query government records and return structured results. The same functions are callable from Python and from the CLI without an AI model; they are not yet a supported public API (decision 0015 in design/architecture.md), so a release may rename them.
The browser demos use recorded responses and require no installation. To run the tools locally, install uv and Git, then run these commands in a macOS or Linux terminal:
git clone https://github.com/pranava0x0/Commonwealth-MCP.git
cd Commonwealth-MCP
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -e . --group dev
.venv/bin/python examples/one_address_every_question.pyThe example prints results for an address in Sterling: a parcel found in
statewide records, a zoning coverage gap, and no matching landmark records
within the query radius. It runs offline by default. Add --live to query
the government services. See examples/ for other workflows, including
a meeting-to-vote example.
On Windows, virtual-environment executables live under .venv\Scripts\.
To point an AI client at the server, let the CLI write the config:
.venv/bin/commonwealth configure claude-code # or claude, cursor, vscode, codexIt fills in the absolute path to this checkout. Add --dry-run to see the
change without making it.
Without a checkout
The source manifests, the jurisdiction table and the skills ship inside the package, so a wheel works on its own:
uv tool install commonwealth-mcp # once it is published; see issue #40
commonwealth doctor
commonwealth skills list # where the bundled skills are on diskuv tool install puts the command on your PATH with its own environment.
uv pip install would refuse here, because it installs into a virtual
environment and this path has none.
The examples, the recorded fixtures and the tests are repo-only.
Server and skills in one install
plugins/commonwealth-mcp/ is a plugin bundle: the server entry and the
workflow skills together. In a client that reads a marketplace:
/plugin marketplace add pranava0x0/Commonwealth-MCP
/plugin install commonwealth-mcp@commonwealth-mcpInstall the package first, so commonwealth serve is on the path. For a
client with no plugin system, commonwealth configure <client> writes the
server entry. Clients with MCP prompt support can list and open each
workflow directly. For file-based discovery, copy a directory printed by
commonwealth skills list into the client’s skills folder.
Related MCP server: local-dfw-mcp
What works
Question | Registered sources |
Which government covers a place? | Names, FIPS codes, addresses, ZIP codes and coordinates; the table contains 133 counties and independent cities and 189 towns |
What parcel is here? | Fairfax County, Loudoun County, Richmond City, Charles City County, the Town of Leesburg, and VGIN statewide parcels |
How is a parcel zoned? | Fairfax and Loudoun counties, Richmond and Winchester cities, and the towns of Leesburg and Vienna. In Winchester the city publishes base districts; overlays are separate. A point in Vienna returns the town's layer and the county's, both unranked |
Which address points, buildings, roads or public places are nearby? | VGIN statewide layers; VDOT road routes |
Which water-quality stations are nearby? | DEQ monitoring stations, including historical stations |
Where is a government boundary? | VGIN locality and town polygons |
What does a Code of Virginia section say? | Section lookup by citation |
Which part of the Code covers this subject? | The Code's own table of contents: titles, chapters, sections. A walk to a citation, not a full-text search — no public endpoint offers one |
When does a local government meet? | Richmond City, Alexandria City, Albemarle County, Hampton City and Petersburg City, from the agenda platform each publishes through. The platform has no cancellation field, so a cancellation is read from the publisher's comment and labelled as a reading |
What was on a meeting agenda, and how did members vote? | Richmond City and Alexandria City publish structured agenda items and individual vote records. An empty vote list does not establish how anyone voted |
Where are the hospitals and urgent care? | Loudoun County's own map of them — a county's list, not a state licensing register, with no hours or services |
A registered statewide layer does not guarantee complete or current records for every place. Read each result's sources, dates, coverage and warnings. School attendance zones, transit service areas and other special districts are not resolved by the locality table.
Virginia's independent cities are separate from counties. A mailing city may differ from the governing locality, and towns can span counties. Ambiguous names return candidates for the caller to choose from.
When two registered sources cover a query, both can be returned. Their records remain separate. Zoning results describe GIS records; confirm applicable requirements with the locality and its adopted ordinance.
No matching records means the query found none in the sources checked. A registry gap means no source is registered for that question and place. Neither establishes that a feature or service does not exist.
Use an AI client
Preview a client configuration change:
.venv/bin/commonwealth configure claude-code --dry-runRemove --dry-run to write it. Other supported configuration targets are
claude, codex, cursor, and vscode. Existing server entries are
preserved. The server uses local stdio transport:
.venv/bin/commonwealth serveFor a client used only for meeting and Code research, configure the civic server. The geo server includes parcels, zoning and other spatial tools:
commonwealth configure claude-code --profile civic
commonwealth configure claude-code --profile geoThese write separate entries, commonwealth-civic and commonwealth-geo.
Each includes registry discovery. Install either on its own or use the
all profile on the existing server to get both domains in one process.
The package also installs commonwealth-civic and commonwealth-geo as
direct stdio launch commands.
Client configuration support does not imply hosted access. There is no public hosted endpoint in this project.
Use the CLI or Python
A live CLI query. A PIN is the number a locality gives a parcel; the spacing inside it is the county's and matters:
.venv/bin/commonwealth tools call geo.find_parcel \
--args '{"jurisdiction": "Fairfax County", "pin": "0102 14 0231"}'The same capability in Python:
import asyncio
from commonwealth.runtime import load_context
from commonwealth.domains.geo import find_parcel
async def main():
result = await find_parcel(
load_context(), jurisdiction="Fairfax County", pin="0102 14 0231")
print(result.model_dump_json(indent=2))
asyncio.run(main())Results include data, source references, retrieval dates, coverage and
warnings. Large retrieved results may have a commonwealth:// resource
handle with an expiry, normally 24 hours. A handle contains what was
retrieved; it does not remove upstream query limits.
What remains
Directly integrated local sources cover a handful of places: Fairfax,
Loudoun and Charles City counties, Richmond and Winchester cities, and the Towns of Leesburg
and Vienna for parcels and zoning, and five localities for public
meetings. Adding another locality's layer is the most useful contribution
and the best-documented path (CONTRIBUTING.md); the
state's open-data portal lists many of them. Run
commonwealth sources discover "zoning" to find candidate publisher services.
Packaging landed on 2026-09-08: the source manifests, the jurisdiction table and the skills ship inside the wheel, so an install works without a checkout. What remains before the server is published is a release version and the upload itself (issue #40). State legislation and full-text Code search are tracked in issue #11 and issue #12. The legislature publishes bills and votes as keyless bulk files (design/source-quirks.md § 20), so #11 waits on an adapter rather than a key. #12 waits on the publisher, whose search backend reports itself down.
Budgets, procurement, school statistics, transit, permits and service requests need source discovery and adapters. They are proposed areas of work, not available tools. The development priorities explain the order and acceptance criteria.
Develop and contribute
COMMONWEALTH_DENY_NETWORK=1 .venv/bin/pytest
.venv/bin/python tools/build_site.py --fixtures
python3 tools/check_writing.py --codeThe tests replay recorded government responses. To check current service
availability separately, run .venv/bin/commonwealth doctor --live.
Location | Purpose |
Runnable workflows | |
Source onboarding and development checks | |
Current architecture, contracts and planned work | |
| Python implementation |
| Source manifests and jurisdiction records |
| The plugin bundle: the server entry, the client manifests, and |
| Offline tests and workflow evaluations |
Published site and audit records | |
Historical research; verify dated claims before reuse |
License
Code: Apache-2.0. Registry: CC0. Documentation prose: CC-BY-4.0. Recorded government responses retain their publishers' terms. See NOTICE and THIRD_PARTY_DATA.yml.
Available Tools
5 toolscivic.get_code_sectionARead-only
Get the text of a Code of Virginia section by its citation (e.g. '1-500', '18.2-57'). Direct lookup only — this is not a full-text search; the caller must already know or have found the section number. Results carry the section's own citation history exactly as published, with a link to the live page. A missing section (repealed, renumbered, or never existed) returns found=False, not an error.
Inputs: citation (required). Returns: data, coverage, evidence, warnings, +5 more
geo.find_boundariesARead-only
Get a Virginia jurisdiction's official boundary: FIPS, GNIS, area, jurisdiction type, bounding box, and the publisher's own centroid. Use to confirm WHICH government's territory is meant and how big it is. Independent cities are returned as their own territory, never as part of the county sharing their name. Screening geometry only — it is generalized and the publisher disclaims survey use, so never decide from it which side of a boundary an address sits on. Pass detail='full' for vertices. Not a containment test: to find which jurisdiction covers a point, use registry.resolve_jurisdiction with lon/lat.
Inputs: jurisdiction (required), detail. Returns: data, coverage, evidence, warnings, +5 more
geo.find_parcelARead-only
Find parcel records in a Virginia jurisdiction by parcel PIN or by a lon/lat point. Pass the user's jurisdiction string as given — resolution and its ambiguities are handled here, and candidate lists must go back to the user unchosen. Results carry provenance and coverage; an empty result with coverage.registry='none' means Commonwealth has no source there, not that no parcel exists. Not for street addresses yet (no geocoding in this release).
Inputs: jurisdiction (required), lat, lon, pin. Returns: data, coverage, evidence, warnings, +5 more
geo.find_zoningARead-only
Find the zoning district(s) for a parcel PIN or lon/lat point in a Virginia jurisdiction. Screening only: results state the GIS layer's answer, never a legal determination — repeat the screening_only warning to the user. When two official sources are registered, both are queried and any disagreement is shown, not reconciled. Use geo.find_parcel first when you need the parcel record itself.
Inputs: jurisdiction (required), lat, lon, pin. Returns: data, coverage, evidence, warnings, +5 more
registry.resolve_jurisdictionARead-only
Resolve a Virginia jurisdiction from a name, alias, or FIPS code, or from a lon/lat point by point-in-polygon against official boundaries. Use FIRST whenever a place is named or a coordinate is given: Virginia has independent cities that are not inside the counties sharing their names (Fairfax City is not in Fairfax County), and towns that sit inside a county so BOTH governments apply — read layered_authorities, do not assume the resolved leaf answers everything. Pass query OR lon/lat, never both. If the result carries candidates with requires_user_choice, present them to the user and never pick one yourself. Not for street addresses yet (no geocoding in this release).
Inputs: lat, lon, query. Returns: data, coverage, evidence, warnings, +5 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool addresses a distinct resource/action: jurisdiction resolution, parcel lookup, zoning lookup, boundary geometry, and legal code text. The only potential overlap is between find_parcel and find_zoning, but their outputs are clearly different.
All tools follow a prefix.verb_noun pattern with consistent snake_case: registry.resolve_jurisdiction, geo.find_zoning, geo.find_parcel, geo.find_boundaries, civic.get_code_section. The domain prefixes make grouping and purpose predictable.
With 5 tools, the server is well-scoped for the Virginia civic/geographic domain. Each tool fills a distinct role, and the set is neither bloated nor too sparse.
The set covers the core read-only workflows: resolve a jurisdiction, get boundaries, find a parcel, get zoning, and retrieve a code section. However, there is no full-text search for code sections and no geocoding for street addresses, so agents must already know section numbers or accept coordinates/PINs. These are explicitly out of scope but still limit the surface.
Maintenance
Related MCP Connectors
Local government intelligence for AI agents.
Resolve any government entity worldwide and submit service requests. Open civic data for AI agents.
U.S. civic data for AI agents: reps, votes, bills, finance, lobbying, cited gov sources. 47 tools.
US public-records intelligence for AI agents — companies, SEC, courts, spending, licenses.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables searching and querying Virginia Open Data (datahub.va.gov) via the Socrata API, providing tools to search datasets, run SoQL queries, and retrieve metadata.92 npmMIT
- AlicenseAqualityDmaintenanceEnables AI assistants to answer DFW civic and property questions using official data sources without API keys.976 npm2Apache 2.0

Akil MCPofficial
AlicenseNot gradedqualityCmaintenanceEnables AI agents to query NYC public records through a hosted MCP server, supporting civic workflows such as property research, business evaluation, public money tracking, and influence mapping.10 npmMIT- FlicenseNot gradedqualityCmaintenanceEnables AI agents and developers to look up zoning, land-use, and development records for Gwinnett County, Georgia through five public read-only tools: resolving an address to its actual governing jurisdiction, searching and retrieving county zoning cases, fetching ordinance code sections, and listing jurisdictions. It exposes the same operations over a REST API so questions about setbacks, permits, and case histories can be answered from indexed source records rather than guesses.-