Skip to main content

MCP Server

The Model Context Protocol is a standard for AI clients (Claude Desktop, Claude Code, Cursor, etc.) to talk to external tools and data sources. govql-mcp-server is the official MCP server for GovQL — once installed, an AI agent can query the GovQL GraphQL API in one tool call without you having to teach it where the endpoint lives or how to format queries.

Install​

Prerequisite: uv (or pipx)​

govql-mcp-server is published on PyPI. To install it on demand from an MCP client, you'll need a Python package runner — most users install uv (one curl command, then every Python MCP server works automatically). If you already have pipx, that works as a drop-in alternative — see the "Other clients" note below.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

This is the same prerequisite used by the broader Python MCP ecosystem — once uv is in place, you won't need to do anything extra for future Python-based MCP servers either.

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 root (or ~/.mcp.json for global):

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

Cursor​

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

Other clients​

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

Prefer pipx over uv? Install with pipx install govql-mcp-server, then use "command": "govql-mcp-server" (no args) in your client config.

Try it​

Once installed, try a question like:

"How did Vermont's two senators vote on the most recent nomination?"

The agent will use list_types and describe_type to learn the schema as needed, then write and run a GraphQL query against votes + votePositions via execute_graphql, then summarize.

Or for something with more analysis:

"In the most recent Congress, which 5 senators broke with their party most often on cloture votes?"

The agent figures out the joins and aggregations.

Tools exposed​

ToolPurpose
execute_graphqlRun any GraphQL query and get the result back. Includes a last_ingest timestamp so the agent can reason about data freshness.
list_typesReturns the names and kinds of every type in the schema. Optional kind filter (e.g. "OBJECT") to narrow further.
describe_typeReturns one type's full details — fields, arg signatures, input fields, enum values — by name.

Limitations​

These limits are enforced by the GovQL API itself — the MCP server simply surfaces the errors:

  • Max query depth: 10. Deep nested queries get rejected.
  • Max query complexity: ~10 billion points. first: N multiplies child cost by N, so very large page sizes on deeply nested queries can trip this.
  • Rate limit: 100 requests / 60 s per source IP. When triggered, you'll get HTTP 429 responses.

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