`get_team_matches`

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

A team’s matches across competitions. Filter by status, date range, competitions, season, or venue.

Parameters

Name	Type	Required	Description
`team_id`	number	yes	Numeric team ID
`status`	string	no	Match status filter
`date_from`	string	no	YYYY-MM-DD
`date_to`	string	no	YYYY-MM-DD
`venue`	string	no	HOME \| AWAY
`season`	number	no	Season start year
`limit`	number	no	Cap matches returned (default 50)

Example call

Arguments

{
  "team_id": 64
}

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_team_matches","arguments":{"team_id":64}}}'

TypeScript (@pipeworx/sdk)

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

const result = await pipeworx.call('get_team_matches', {
  "team_id": 64
});

More examples

{
  "team_id": 64,
  "status": "FINISHED",
  "venue": "HOME",
  "limit": 20
}

Response shape

Always returns: team_id, count, matches

Field	Type	Description
`team_id`	number	Team ID queried
`count`	number	Number of matches returned
`matches`	array

Full JSON Schema

{
  "type": "object",
  "properties": {
    "team_id": {
      "type": "number",
      "description": "Team ID queried"
    },
    "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"
          },
          "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 '-')"
          },
          "score_half_time": {
            "type": [
              "string",
              "null"
            ],
            "description": "Half-time score (e.g., '1-0' or '-')"
          },
          "winner": {
            "type": [
              "string",
              "null"
            ],
            "description": "Winner ('HOME', 'AWAY', 'DRAW', or null)"
          },
          "venue": {
            "type": [
              "string",
              "null"
            ],
            "description": "Venue name"
          }
        }
      }
    }
  },
  "required": [
    "team_id",
    "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_team_matches