`list_races`

Pack: us-race-matchups · Connect: https://pipeworx.io/mcp (see Connect below for a single-pack URL)

No MCP client? Call it directly: GET https://gateway.pipeworx.io/v1/tools/list_races for the schema, then POST the same URL with its arguments for the data.

Every federal race in a state for a cycle (the Senate seat if any, and each House district) with how many candidates registered with the FEC and who the incumbent is. Use it to find the district number before calling race_matchup.

Parameters

Name	Type	Required	Description
`state`	string	yes	US state: postal code (“IA”) or full name.
`office`	string	no	Optional: “house” or “senate” to restrict.
`cycle`	number	no	Election year, even. Default 2026.

Example call

Arguments

{
  "state": "Iowa"
}

curl

curl -X POST https://gateway.pipeworx.io/us-race-matchups/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_races","arguments":{"state":"Iowa"}}}'

TypeScript (@pipeworx/sdk)

import { Pipeworx } from '@pipeworx/sdk';
const pipeworx = new Pipeworx();

const result = await pipeworx.call('list_races', {
  "state": "Iowa"
});

Response shape

Field	Type	Description
`state`	string
`cycle`	number
`races_total`	number
`races`	array
`note`	string
`source`	string
`data_as_of`	string \| null
`data_as_of_note`	string

Full JSON Schema

{
  "type": "object",
  "properties": {
    "state": {
      "type": "string"
    },
    "cycle": {
      "type": "number"
    },
    "races_total": {
      "type": "number"
    },
    "races": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "office": {
            "type": "string"
          },
          "district": {
            "type": [
              "string",
              "null"
            ]
          },
          "candidates_registered": {
            "type": "number"
          },
          "incumbent": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      }
    },
    "note": {
      "type": "string"
    },
    "source": {
      "type": "string"
    },
    "data_as_of": {
      "type": [
        "string",
        "null"
      ]
    },
    "data_as_of_note": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

Connect

Add this to your MCP client config — every tool in the catalog, including this one — or use one-click install buttons:

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://pipeworx.io/mcp"
    }
  }
}

Connect to just the us-race-matchups pack

{
  "mcpServers": {
    "us-race-matchups": {
      "url": "https://gateway.pipeworx.io/us-race-matchups/mcp"
    }
  }
}

See Getting Started for client-specific install steps.

list_races