`search_candidates`

Pack: open-fec · Endpoint: https://gateway.pipeworx.io/open-fec/mcp

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

Search federal election candidates by name, state, or party. Returns candidate ID, name, party, office, state, district, and election years. Example: search_candidates(“Biden”, state=“DE”, party=“DEM”)

Parameters

Name	Type	Required	Description
`_apiKey`	string	yes	OpenFEC API key
`query`	string	yes	Candidate name to search (e.g., “Sanders”)
`state`	string	no	Two-letter state code (e.g., “CA”, “NY”)
`party`	string	no	Party code: “DEM”, “REP”, “LIB”, “GRE”, etc.

Example call

Arguments

{
  "query": "Sanders",
  "_apiKey": "your-open-fec-api-key"
}

curl

curl -X POST https://gateway.pipeworx.io/open-fec/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_candidates","arguments":{"query":"Sanders","_apiKey":"your-open-fec-api-key"}}}'

TypeScript (@pipeworx/sdk)

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

const result = await pipeworx.call('search_candidates', {
  "query": "Sanders",
  "_apiKey": "your-open-fec-api-key"
});

More examples

{
  "query": "Biden",
  "state": "DE",
  "party": "DEM",
  "_apiKey": "your-open-fec-api-key"
}

Response shape

Always returns: total, returned, candidates

Field	Type	Description
`total`	number	Total count of candidates matching search criteria
`returned`	number	Number of candidates returned in this response
`candidates`	array	Array of candidate records

Full JSON Schema

{
  "type": "object",
  "properties": {
    "total": {
      "type": "number",
      "description": "Total count of candidates matching search criteria"
    },
    "returned": {
      "type": "number",
      "description": "Number of candidates returned in this response"
    },
    "candidates": {
      "type": "array",
      "description": "Array of candidate records",
      "items": {
        "type": "object",
        "properties": {
          "candidate_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "FEC candidate ID"
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Candidate full name"
          },
          "party": {
            "type": [
              "string",
              "null"
            ],
            "description": "Party affiliation"
          },
          "state": {
            "type": [
              "string",
              "null"
            ],
            "description": "State code"
          },
          "district": {
            "type": [
              "string",
              "null"
            ],
            "description": "Congressional district"
          },
          "office": {
            "type": [
              "string",
              "null"
            ],
            "description": "Office sought (President, Senator, Representative, etc.)"
          },
          "incumbent_challenge": {
            "type": [
              "string",
              "null"
            ],
            "description": "Incumbent or challenger status"
          },
          "status": {
            "type": [
              "string",
              "null"
            ],
            "description": "Candidate status"
          },
          "election_years": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "Years candidate ran in elections"
          },
          "has_raised_funds": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether candidate has raised campaign funds"
          }
        }
      }
    }
  },
  "required": [
    "total",
    "returned",
    "candidates"
  ]
}

Connect

Add this to your MCP client config, or use one-click install buttons:

{
  "mcpServers": {
    "open-fec": {
      "url": "https://gateway.pipeworx.io/open-fec/mcp"
    }
  }
}

See Getting Started for client-specific install steps.

search_candidates