GovQL

govql-mcp-server

An MCP (Model Context Protocol) server for GovQL — gives AI clients like Claude Desktop, Claude Code, and Cursor direct access to the US Congressional GraphQL API at api.govql.us/graphql without bespoke HTTP wiring.

For the design rationale (why FastMCP-Python, the passthrough+curated philosophy, roadmap through v0.4), see design.md.

What you can do with it

Ask an agent questions like:

• "How did Vermont's two senators vote on the most recent nomination?"
• "Which legislators in the 118th Congress switched parties during their service?"
• "Who represents Arizona's 3rd congressional district?"
• "Compare Senator Sanders' voting record to Senator Murkowski's on cloture votes in the most recent Congress."
• "Which Democrats most often voted with Republicans in the current Congress?"

The agent picks the right tool, writes the GraphQL query against the live schema, and parses the response — no manual API wrangling.

Install

The server runs as a per-client subprocess over stdio. Pick your client:

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "govql": {
      "command": "uvx",
      "args": ["govql-mcp-server"]
    }
  }
}

Restart Claude Desktop. The govql tools appear in the tools panel.

Claude Code

Add to .mcp.json in your project (or ~/.mcp.json for global):

{
  "mcpServers": {
    "govql": {
      "command": "uvx",
      "args": ["govql-mcp-server"]
    }
  }
}

Cursor

Settings → MCP → Add Server. Use the same command / args as above.

Other clients

Any MCP-compatible client that supports stdio servers will work. The command is uvx govql-mcp-server with no required arguments.

Tools

Tool	Purpose
execute_graphql	Run any GraphQL query against the GovQL endpoint. Returns the result plus an last_ingest timestamp so the agent can reason about data freshness.
list_types	Returns the names and kinds of every type in the GovQL schema. Optional kind filter ("OBJECT", "INPUT_OBJECT", "ENUM", etc.) to narrow further. Start here when you don't know what's queryable.
describe_type	Returns one type's full details — fields, arg signatures, input fields, enum values. Call after list_types to learn the shape of a specific type before writing a query.
find_legislator	Find members by name, party, state, chamber, or district when you don't know a bioguide id. Party/state/chamber/district match the member's terms (district is House-only); current_only (default) restricts to sitting members. Returns a compact list — each member's bioguideId plus current party/state/chamber/district.
find_vote	Browse roll-call votes by category, chamber, or congress (newest first), or keyword-search the vote question. topic matches the question text (which includes bill short titles) — not a full subject index, so it misses procedural votes, and bill subjects aren't populated yet. Returns a compact list with each voteId.
get_legislator	Full detail for one member by bioguide id: names, bio, and complete term history (party/state/chamber/district over time) with a current block.
get_vote_with_positions	One vote by id with tallies and per-party breakdown; optionally the individual member positions (filter by party/state/position).
get_voting_record	A member's voting behavior per congress: participation rate and party-loyalty rate, from the precomputed summaries.
compare_voters	How often two members voted the same way, per congress+chamber, with an agreement rate.
find_party_defectors	Members who least often voted with their own party's majority in a congress; optional party/chamber filters.

Configuration

All env vars are optional — the package is zero-config for end users.

Env var	Default	Purpose
GOVQL_ENDPOINT	https://api.govql.us/graphql	Endpoint to query. Override to point at a local dev stack.
GOVQL_TIMEOUT_MS	30000	Per-request HTTP timeout.
LOG_LEVEL	INFO	Logging level. Logs go to stderr only (stdout is reserved for the MCP transport).

Limits (enforced by the upstream API)

• Max query depth: 10
• Max query complexity: ~10 billion points (first: N multiplies child cost by N — keep page sizes reasonable on deeply nested queries)
• Rate limit: 100 requests / 60 s per source IP

A depth or complexity violation surfaces as a GraphQL errors entry in the tool response so the agent can adjust and retry.

Data freshness

Every execute_graphql response includes a last_ingest ISO timestamp. Vote data refreshes hourly; legislator data refreshes daily.

Status

As of 0.4.0, the server provides the three foundational tools (execute_graphql, list_types, describe_type) plus the curated discovery tools (find_legislator, find_vote), per-entity detail tools (get_legislator, get_vote_with_positions), and analysis tools (get_voting_record, compare_voters, find_party_defectors) — the curated discovery/detail/analysis set is now complete. The remaining most_agreeing_pairs and bill/committee tools are post-v0.4: the bill/committee tools await GovQL data population, and most_agreeing_pairs awaits a server-side cross-party ranking aggregate — see design.md.

Links

• GovQL project site
• GraphQL API
• Source / issues