va-lis-mcp

An MCP server for the Virginia Legislative Information System (LIS) REST API. It exposes the Virginia General Assembly's sessions, bills and keyword search, summaries, full bill text and versions, action history, votes and roll calls, members, committees, meetings, minutes books, communications between the chambers, and session statistics to any MCP client (Claude Code, Claude Desktop, and others). Every tool is read only. You bring your own LIS API key.

Built on va-lis-client, a Python client for the LIS API.

Requirements

• Python 3.10 or newer
• uv, which provides the uvx launcher used below. Install it with one line: curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) or powershell -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows)
• A LIS API key (next section)

Getting an API key

Register for a free partner key at https://lis.virginia.gov/apiregistration. The key is a GUID. The server reads it from the LIS_API_KEY environment variable.

LIS heartbeat endpoints accept any key, even garbage, so a successful ping proves nothing. Use the check_api_key tool to confirm the key is registered and active.

Install and configure

Claude Code

claude mcp add va-lis -e LIS_API_KEY=your-guid-here -- uvx va-lis-mcp

Claude Desktop and other MCP clients

Add this to the client's MCP configuration (for Claude Desktop that is claude_desktop_config.json):

{
  "mcpServers": {
    "va-lis": {
      "command": "uvx",
      "args": ["va-lis-mcp"],
      "env": { "LIS_API_KEY": "your-guid-here" }
    }
  }
}

Installing from source

To run the server from a checkout, point the client at it instead:

git clone https://github.com/JonnyWaffles/va-lis-mcp
claude mcp add va-lis -e LIS_API_KEY=your-guid-here -- uv run --directory /path/to/va-lis-mcp va-lis-mcp

The same works in a JSON config with "command": "uv" and "args": ["run", "--directory", "/path/to/va-lis-mcp", "va-lis-mcp"].

Tools

Every tool returns compact JSON. Bills are addressed by bill number plus session code, members by member_id, and committees by number (H08) or name.

Sessions and bills

Votes

Members

Committees

Meetings

Chamber records

Statistics

Diagnostics

Errors come back as readable tool errors. A bill lookup that misses names the bill and session it searched; an ambiguous committee name lists the matches; an unknown member id points at list_members; a missing key tells you to set LIS_API_KEY and where to register.

Domain notes

Distilled from the va-lis-client documentation, which is the full reference for LIS behavior.

• Session codes encode year plus sequence: 20261 is the 2026 Regular Session, 20262 is 2026 Special Session I. Most tools require one.
• Bill numbers are unpadded. LIS returns nothing for HB0001; the correct form is HB1. The tools normalize input (hb0001 becomes HB1), so you can pass either.
• The default session tracks the GA's working session. Once a session wraps up, the default advances to the upcoming session during the interim. By August 2026 it already pointed at 20271. For retrospective work on a session that just ended, pass its explicit session code.
• Carry over reuses bill IDs. A bill from an even year session may be carried over into the following odd year session (never the reverse, at most once). The carried bill keeps its numeric LegislationID in both sessions, so a bill is identified by session code plus bill number. The sessions list on get_bill is the lineage record: two entries mean the bill was carried over.
• Passage dates live in the history. The bill detail's passage date fields are always null in LIS; get_bill_history flags passage events and carries the vote tallies.
• Votes reach a bill through its history. No LIS vote endpoint accepts a bill id, so get_bill_votes walks the bill's events and fetches the vote behind each one. get_bill_history carries the vote_id on each event.
• A block vote is not a position on one bill. A chamber bundles its uncontroversial bills and passes them in one motion; one 2026 House vote disposed of 105 bills at 97 to 0. A voice vote records no members at all. get_roll_call leaves both out, get_bill_votes flags them, and get_member_votes marks each row with is_block.
• Not voting is not in the tally. Members recorded as not_voting (LIS code X) are omitted from the tally string, so the member groups never add up to it. Vote statements are corrections a member filed afterwards; the recorded roll call is never amended.
• The roster is larger than the chamber, on purpose. A session roster includes members who left or arrived mid-session, because they cast the votes recorded before they left. list_members keeps them and marks the departure date and reason.
• Committees are not session scoped; their seats are. The committee list describes the committees that exist now, and get_committee reads the seat list for the session you name. LIS has no "bills referred to a committee" endpoint; get_bill_history names the committee that holds a bill.
• Dockets are Senate only. House committee agendas are not in the API: list_meetings gives the meeting, the bill's history gives the referral, and the agenda itself lives on the committee's web page. Schedule times are free text as the clerk entered them and may be blank.
• Two ways to find a bill. list_bills matches the number and the short description of every bill in a session. search_bills is the full text search over summaries or bill text. LIS drops common words from a keyword, so a word such as "the" finds nothing.
• A filtered search hides failed bills. A keyword search on its own includes them. Once the search names a stage or a patron, LIS leaves out failed and incorporated bills (measured in October 2026). The tool matches the chamber itself for that reason, and the response says so when the gap applies.
• A minutes book is the safe way in to a roll call. A vote_id on a bill's history can point at a vote that disposed of some other bill. A vote_id in get_minutes_book belongs to the bill beside it. The minutes tally also keeps a presiding officer's tiebreak, which the vote record drops.
• Only the Senate publishes floor minutes. Both chambers publish committee books. For House floor action, read list_floor_calendars and get_bill_history.
• A communication names bills, never votes. It is the formal message one chamber's clerk sends the other. Structured content starts in May 2024; an older communication is an HTML file and nothing more.
• The fast vote list knows less. get_bill_vote_tallies and list_votes cost one request per chamber, however many votes there are. They leave out most voice votes, carry no pass or fail flag, and do not say how many bills a block vote covered. get_bill_votes has all three.
• LIS's statistics are its own arithmetic. The session and committee counts name no bill, and they do not always agree with the bill list. A total can miss by a bill, and the committee counts are referrals, not bills. Count from list_bills when a number has to be exact.
• Staff and offices are not session scoped. get_committee_staff names who serves a committee now. get_member_office reads the district office, and many members have none on record.

Embedding in an ASGI app

Besides stdio, the server can be served over streamable HTTP. The packaged ASGI app is stateless and returns plain JSON, so it works behind multiple workers without sticky sessions:

uvicorn va_lis_mcp.asgi:app --workers 4

The MCP endpoint is at /mcp. To mount it inside a larger Starlette (or any ASGI) application, the host app's lifespan must run the MCP session manager:

from contextlib import asynccontextmanager

from starlette.applications import Starlette
from starlette.routing import Mount

from va_lis_mcp.server import mcp


@asynccontextmanager
async def lifespan(app):
    async with mcp.session_manager.run():
        yield


app = Starlette(
    routes=[
        Mount("/lis", app=mcp.streamable_http_app(stateless_http=True, json_response=True)),
    ],
    lifespan=lifespan,
)

That serves the endpoint at /lis/mcp. Keep stateless_http=True whenever more than one worker handles requests: the default stateful transport needs every request of a session to reach the same worker, which a plain worker pool does not guarantee.

This is ASGI only; a WSGI stack cannot host it. Django projects can still serve it, but through their ASGI entry point (for example gunicorn with uvicorn workers), not through WSGI.

Development

uv venv
uv pip install -e ".[dev]"
uv run pytest
uv run ruff check .

Poke at the tools interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector uv run va-lis-mcp

Upgrading

uvx caches resolved environments, so after a new release force resolution of the latest version:

uvx va-lis-mcp@latest

License

MIT