govql-mcp-server 0.1.0

MCP server for GovQL — query US Congressional data via GraphQL from any MCP client.

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?"
• "Compare Senator Sanders' voting record to Senator Murkowski's on cloture votes in the most recent 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.

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

Version 0.1.0 ships three foundational tools: a GraphQL passthrough (execute_graphql) and two narrow schema-discovery tools (list_types, describe_type). Curated higher-level tools (find_legislator, get_voting_record, compare_voters, etc.) are planned for subsequent releases — see design.md for the roadmap.

Links

• GovQL project site
• GraphQL API
• Source / issues