Building with AI? Give your coding tool the whole reference in one file: https://soccer-data.co/llms.txt
SOCCER DATA Docs
Sign in Get API key
// Get started

MCP server

Connect Claude, ChatGPT, Cursor and other AI apps to Soccer Data, and ask about football in plain English.

Soccer Data has an MCP server. MCP (Model Context Protocol) is the standard way for AI apps to use outside tools. Once you connect it, an assistant such as Claude or ChatGPT can look up fixtures, scores, lineups, stats, xG, standings and odds while you chat, and answer from real data instead of from memory.

You don't write any code. You add one URL to your AI app, sign in to Soccer Data, and start asking:

  • "Who's top of the Premier League, and how have the top three done in their last five?"
  • "Compare Saka and Salah this season, per 90 minutes."
  • "Which matches are live right now, and what are the scores?"
  • "Preview Arsenal's next match: form, injuries and the odds."

Plans and limits

The MCP server is part of the Pro and Business plans. On the Free plan, connected apps can make 10 calls a day so you can try it.

Each tool call that fetches data counts as one request against your daily limit, the same as an API call. MCP calls share your plan's per-minute and daily limits with your API keys. The get_usage tool, which shows what's left today, is free. Your usage page lists MCP calls with the source MCP.

The server URL

https://soccer-data.co/mcp

Enter it exactly as shown, with no slash at the end. The server uses the Streamable HTTP transport. You can sign in two ways:

  • Sign in with your account (OAuth). Claude, ChatGPT, Cursor and VS Code send you to Soccer Data to approve the app. There's no key to copy, and you can disconnect the app at any time.
  • An API key in a header. For tools that take headers, send X-Api-Key: YOUR_API_KEY, or Authorization: Bearer YOUR_API_KEY. Create a separate key for each tool on the API keys page, so you can revoke one without affecting the others.

The MCP server page in your dashboard shows the URL and ready-to-copy setup for each app.

Claude

This works on claude.ai, the Claude desktop apps and mobile. Once the connector is added on one of them, it's there on all of them.

  1. Open Customize → Connectors, click + and choose Add custom connector.
  2. Name it Soccer Data and paste the server URL.
  3. If Claude asks how to register the OAuth client, choose Register automatically. Leave the client ID and secret empty.
  4. Click Add, then Connect. Sign in to Soccer Data if asked, and click Approve.

In a chat, open the tools menu to check that Soccer Data is on. Then ask your question.

Note On Team and Enterprise plans, an owner adds the connector first under Organization settings → Connectors. Each member then finds Soccer Data under Customize → Connectors and clicks Connect, so every member uses their own Soccer Data account.

ChatGPT

  1. Go to Plugins, click + and choose Add custom MCP server.
  2. Name it Soccer Data, add a short description, paste the server URL and choose OAuth for authentication.
  3. Accept the warning about custom servers, and create it. Approve Soccer Data when you're asked to sign in.
  4. In a new chat, type @ and pick Soccer Data.

Custom MCP servers depend on your ChatGPT plan and, in a workspace, on what your admin allows. In a Business workspace, an admin or owner adds the server. ChatGPT can't send API keys, so it always uses sign-in.

Claude Code

Add the server, then sign in from Claude Code:

claude mcp add --transport http soccer-data https://soccer-data.co/mcp

Run /mcp, pick soccer-data and choose to authenticate. Your browser opens so you can approve it. Add --scope user to make it available in every project.

To use an API key instead of signing in:

claude mcp add --transport http soccer-data https://soccer-data.co/mcp --header "X-Api-Key: YOUR_API_KEY"

Cursor

Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json to use it in one project only:

{
  "mcpServers": {
    "soccer-data": {
      "url": "https://soccer-data.co/mcp"
    }
  }
}

In Cursor's MCP settings, click Connect next to soccer-data and approve it. To use a key instead, add "headers": { "X-Api-Key": "${env:SOCCER_DATA_KEY}" } next to url, and set SOCCER_DATA_KEY in your environment.

VS Code

Save this as .vscode/mcp.json, or run MCP: Add Server, choose HTTP and paste the URL:

{
  "servers": {
    "soccer-data": {
      "type": "http",
      "url": "https://soccer-data.co/mcp"
    }
  }
}

VS Code asks you to sign in the first time it starts the server. To use a key, add a headers object with X-Api-Key. Use an inputs prompt to fill it in, so the key isn't saved in the file.

Other apps

Any app that supports remote MCP servers over Streamable HTTP can connect:

  • If it supports OAuth, give it the URL. It reads our sign-in details from /.well-known/oauth-protected-resource/mcp and registers itself.
  • If it can only send headers, send X-Api-Key: YOUR_API_KEY.
  • If it only runs local (stdio) servers, put a bridge such as mcp-remote in between and pass the header through it.

What the app can access

When you approve an app, it can read football data on your behalf and see your plan and today's usage. It can't see your API keys, your billing details or your password, and it can't change anything in your account.

To disconnect an app, open the MCP server page and click Disconnect next to it. It stops working at once, and it has to ask for your approval again to reconnect. Apps that use an API key stop when you revoke the key.

Tools

Every API endpoint is a tool, with the same parameters as in the API reference. Two helpers come first:

  • find_ids turns a competition, team or player name into an id. Assistants call it before anything that needs an id, so they never guess one.
  • get_usage shows your plan, the requests left today and when they reset. It's free.
Tool What it does
find_ids Find ids by name
get_usage Plan and usage today
competitions_list Search competitions
competitions_show Competition details
competitions_seasons Seasons of a competition
competitions_groups Groups in a tournament season
competitions_standings League table
teams_list Search teams
teams_show Team details
teams_players Team squad
teams_injuries Team absences
teams_stats Team season record
teams_standings Where a team has tables
matches_list List matches
matches_show Get a match
matches_lineups Get match lineups
matches_stats Get match stats
matches_live_stats Get live match stats
matches_player_stats Get match player stats
matches_live_player_stats Get live match player stats
matches_timeline Get match timeline
matches_live_timeline Get live match timeline
matches_shotmap Get match shot map
matches_referee Get match referee
matches_player_heatmap Get match player heatmap
players_list Search players
players_show Player details
players_stats Player season stats
players_injuries Player absences
players_season_heatmap Player season heatmap
odds_prematch Pre-match odds
odds_live Live odds
coverage_leagues Data coverage per competition
coverage_league Season coverage for a competition
coverage_summary Coverage at a glance

All tools only read data. Odds tools need a paid plan, as in the API.

Prompts

Apps that support MCP prompts (for example in Claude's + menu, or as / commands in Claude Code) also get these ready-made prompts:

Prompt What it does
match_preview Previews the next match between two teams: form, table, absences and odds.
compare_players Compares two players' season stats side by side, per 90 minutes.
league_table Shows a competition's table for any season, with each team's form.
live_now Lists every match in play, optionally for one competition.

Getting good answers

  • Name the competition and season when it matters. "Real Madrid's 2023/24 La Liga record" gets one precise call, where "how did Madrid do" may take several.
  • Ask for what you need. A broad question such as "every Premier League match this season" can take many calls, and each one counts.
  • Check the coverage. xG, player stats and odds aren't available for every competition. The assistant can check with the coverage tools first. See Coverage.
  • Live answers are as fresh as your plan. Paid plans refresh live data every 15 seconds, and Free every 5 minutes. See Rate limits.

Troubleshooting

Problem What to do
The app says the URL is invalid, or sign-in fails straight away Check the URL is exactly https://soccer-data.co/mcp, with no slash at the end. In Claude, choose Register automatically for the OAuth client.
invalid_token or "API key is not valid" The key was revoked or mistyped, or the app was disconnected. Create a new key, or connect the app again.
"Today's MCP calls are used up" The Free plan's 10 daily calls are spent. They reset at midnight UTC, or you can upgrade.
PLAN_UPGRADE_REQUIRED The tool needs a paid plan, as odds do.
USAGE_LIMIT_EXCEEDED or RATE_LIMITED Your plan's daily or per-minute limit is reached. MCP calls share it with your API keys.
The assistant answers without using Soccer Data Make sure the connector is switched on for the chat, or start your question with "Using Soccer Data, …".

Next steps