Skip to main content
Glama

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.py

The 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, codex

It 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 disk

uv 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-mcp

Install 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-run

Remove --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 serve

For 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 geo

These 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 --code

The tests replay recorded government responses. To check current service availability separately, run .venv/bin/commonwealth doctor --live.

Location

Purpose

examples/

Runnable workflows

CONTRIBUTING.md

Source onboarding and development checks

design/

Current architecture, contracts and planned work

src/commonwealth/

Python implementation

sources/

Source manifests and jurisdiction records

plugins/commonwealth-mcp/

The plugin bundle: the server entry, the client manifests, and skills/ — instructions for multi-tool workflows

tests/, evals/

Offline tests and workflow evaluations

docs/

Published site and audit records

research/

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 tools
civic.get_code_sectionA
Read-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_boundariesA
Read-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_parcelA
Read-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_zoningA
Read-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_jurisdictionA
Read-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

    A4.8/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to answer DFW civic and property questions using official data sources without API keys.
      9
      76 npm
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      -