Model Context Protocol (MCP) Server

Enable AI agents to query live football data, statistical models, and odds on behalf of their users.

The Model Context Protocol (MCP) is the open standard for connecting Large Language Models and AI agents to external tools and live data sources. KickoffAPI provides full native MCP support across two deployment modes:

Option 1: Stdio CLI (Local)

`@kickoffapi/mcp`

Zero-dependency Node.js CLI running over standard I/O. Ideal for Claude Desktop, Cursor, Claude Code, and local agent runtimes.

Option 2: Hosted Stream (Cloud)

`api.kickoffapi.com/mcp`

Hosted HTTP & Server-Sent Events (SSE) stream. Zero local processes to install. Ideal for cloud agents, Discord bots, and remote agents.

1. Claude Desktop Setup

Configure Claude Desktop to give Claude immediate access to live matches, tables, and probabilities:

Open your Claude configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kickoffapi": {
      "command": "npx",
      "args": ["-y", "@kickoffapi/mcp"],
      "env": {
        "KICKOFFAPI_KEY": "your_api_key_here"
      }
    }
  }
}

Save the file and restart Claude Desktop. The hammer icon will illuminate, revealing 10 football tools.

2. Cursor IDE Setup

Allow Cursor’s Composer and chat agent to query matches, examine team statistics, or build predictive features:

Create or update .cursor/mcp.json in your repository root:

{
  "mcpServers": {
    "kickoffapi": {
      "command": "npx",
      "args": ["-y", "@kickoffapi/mcp"],
      "env": {
        "KICKOFFAPI_KEY": "your_api_key_here"
      }
    }
  }
}

3. Remote & Hosted SSE Setup

For autonomous agents connecting via Server-Sent Events (SSE) or stateless HTTP JSON-RPC 2.0 without installing local dependencies:

Discovery & Catalog: GET https://api.kickoffapi.com/mcp
SSE Stream: GET https://api.kickoffapi.com/mcp/sse?key=YOUR_API_KEY
Message Endpoint: POST https://api.kickoffapi.com/mcp/messages?sessionId=...
Direct Stateless POST: POST https://api.kickoffapi.com/mcp with x-api-key: YOUR_KEY

Example configuration for agents supporting remote SSE:

{
  "mcpServers": {
    "kickoffapi": {
      "url": "https://api.kickoffapi.com/mcp/sse?key=your_api_key_here"
    }
  }
}

Tool Catalog & Schemas

The KickoffAPI MCP server exposes 10 specialized football tools adhering to the Model Context Protocol specification (protocol version 2024-11-05):

Tool Name	Description	Arguments
get_live_scores	Fetch real-time live match scores, minute, and scorelines.	league_id, timeframe
get_fixtures	Scheduled fixtures by date or league with kick-off times and venues.	date, league_id, status
get_fixture_details	Comprehensive match stats, lineups, substitutions, cards, and goals.	fixture_id (required)
get_standings	League rankings, points, goal difference, and form guide.	league_id (required), season
get_projections	Expected goals (xG), win/draw/loss % and Dixon-Coles score matrix.	fixture_id or home_team_id + away_team_id
get_team_stats	Team performance metrics, recent form, and clean sheets.	team_id (required), league_id
get_player_stats	Goals, assists, minutes, shots, passing, and discipline.	player_id (required), team_id
get_odds	Real-time betting odds (1X2, Over/Under, BTTS) across bookmakers.	fixture_id (required), market
search_teams_and_leagues	Search football clubs, leagues, and venues by name.	query (required), type
get_season_sim	Monte Carlo season simulation, title probabilities, top-4 & relegation odds.	league_id (required)

Example Agent Queries

Once connected, you can converse with your agent naturally:

"Which Premier League matches are playing today, and what are their current live scores?"
"Compare Arsenal and Chelsea's expected goals (xG) projections for their upcoming match."
"Run a simulation of the Serie A season: who is statistically favored to win the title?"
"What are the best available bookmaker odds for Over 2.5 goals in tonight's Champions League match?"

Authentication & Usage

Every MCP tool execution calls the authenticated KickoffAPI v2 endpoints on behalf of the configured API key. Requests count towards your plan's standard daily quotas and inherit your tier's concurrency limits.

Need an API key? Create a free account at kickoffapi.com/signup.html.