`get_competition_matches`

Pack: football-data · Endpoint: https://gateway.pipeworx.io/football-data/mcp

List matches in a competition. Filter by status (SCHEDULED, LIVE, IN_PLAY, PAUSED, FINISHED, POSTPONED, SUSPENDED, CANCELLED), date range, matchday, stage, or season year.

Parameters

Name	Type	Required	Description
`competition`	string	yes	Competition code (e.g., “PL” = Premier League, “PD” = La Liga, “CL” = Champions League)
`status`	string	no	Match status filter (SCHEDULED \| LIVE \| IN_PLAY \| PAUSED \| FINISHED \| POSTPONED \| SUSPENDED \| CANCELLED)
`date_from`	string	no	YYYY-MM-DD
`date_to`	string	no	YYYY-MM-DD
`matchday`	number	no	Round number
`stage`	string	no	Stage (e.g., “GROUP_STAGE”, “QUARTER_FINALS”)
`season`	number	no	Season start year (e.g., 2025)

Example call

Arguments

{
  "competition": "PL"
}

curl

curl -X POST https://gateway.pipeworx.io/football-data/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_competition_matches","arguments":{"competition":"PL"}}}'

TypeScript (@pipeworx/sdk)

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

const result = await pipeworx.call('get_competition_matches', {
  "competition": "PL"
});

More examples

{
  "competition": "CL",
  "status": "FINISHED",
  "season": 2024
}

Response shape

Always returns: competition, count, matches

Field	Type	Description
`competition`	string	Competition code used in the query
`count`	number	Number of matches returned
`matches`	array

Full JSON Schema

{
  "type": "object",
  "properties": {
    "competition": {
      "type": "string",
      "description": "Competition code used in the query"
    },
    "count": {
      "type": "number",
      "description": "Number of matches returned"
    },
    "matches": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": [
              "number",
              "null"
            ],
            "description": "Match ID"
          },
          "utc_date": {
            "type": [
              "string",
              "null"
            ],
            "description": "Match date/time in UTC (ISO 8601)"
          },
          "status": {
            "type": [
              "string",
              "null"
            ],
            "description": "Match status"
          },
          "matchday": {
            "type": [
              "number",
              "null"
            ],
            "description": "Round/matchday number"
          },
          "stage": {
            "type": [
              "string",
              "null"
            ],
            "description": "Competition stage (e.g., GROUP_STAGE)"
          },
          "group": {
            "type": [
              "string",
              "null"
            ],
            "description": "Group name if applicable"
          },
          "competition": {
            "type": [
              "string",
              "null"
            ],
            "description": "Competition name"
          },
          "competition_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "Competition code"
          },
          "home": {
            "type": [
              "string",
              "null"
            ],
            "description": "Home team name"
          },
          "home_id": {
            "type": [
              "number",
              "null"
            ],
            "description": "Home team ID"
          },
          "away": {
            "type": [
              "string",
              "null"
            ],
            "description": "Away team name"
          },
          "away_id": {
            "type": [
              "number",
              "null"
            ],
            "description": "Away team ID"
          },
          "score_full_time": {
            "type": [
              "string",
              "null"
            ],
            "description": "Full-time score (e.g., '2-1' or '-' if not final)"
          },
          "score_half_time": {
            "type": [
              "string",
              "null"
            ],
            "description": "Half-time score (e.g., '1-0' or '-' if not played)"
          },
          "winner": {
            "type": [
              "string",
              "null"
            ],
            "description": "Winner ('HOME', 'AWAY', 'DRAW', or null)"
          },
          "venue": {
            "type": [
              "string",
              "null"
            ],
            "description": "Venue name"
          }
        }
      }
    }
  },
  "required": [
    "competition",
    "count",
    "matches"
  ]
}

Connect

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

{
  "mcpServers": {
    "football-data": {
      "url": "https://gateway.pipeworx.io/football-data/mcp"
    }
  }
}

See Getting Started for client-specific install steps.

get_competition_matches