DEV Community: John Ellis

Give Claude and ChatGPT Live Football Data: Building an MCP Server for a Football API

John Ellis — Wed, 26 Aug 2026 03:40:45 +0000

Ask Claude who's playing tonight and it will politely explain that it doesn't have live data. Ask ChatGPT how the odds moved before a match and you get a lecture about not being able to browse. Both are perfectly capable of reasoning about football — they just can't see the pitch.

The Model Context Protocol (MCP) fixes exactly this. An MCP server is a small program that exposes "tools" — functions with a name, a description and a JSON schema — and any MCP-capable assistant can discover and call them. Wrap a REST API in one and the assistant gains the ability to look things up before it answers.

This post does that for football. In the first half we install a ready-made server and connect it to Claude Code, Claude Desktop, Cursor and ChatGPT. In the second half we open it up and look at how it's built, so you can do the same for any API you care about.

The API underneath is 5DollarFootballAPI: fixtures, live scores, standings, corners, cards, odds and full odds movement history. Disclosure: I build that API, and I wrote the MCP server. Nothing below is specific to it — swap in your own client and the pattern is identical.

Part 1: two minutes to a football-aware assistant

You need Node 18+ and an API key. The free tier (no card) covers fixtures, live scores and standings, which is enough for most of the prompts below.

Claude Code

claude mcp add football-api -e FIVEDOLLARFOOTBALL_API_KEY=fb_live_your_key -- npx -y football-api-mcp

Claude Desktop and Cursor

Both read the same JSON shape. Claude Desktop: claude_desktop_config.json. Cursor: .cursor/mcp.json in the project, or ~/.cursor/mcp.json globally.

{
  "mcpServers": {
    "football-api": {
      "command": "npx",
      "args": ["-y", "football-api-mcp"],
      "env": { "FIVEDOLLARFOOTBALL_API_KEY": "fb_live_your_key" }
    }
  }
}

Restart the app and you should see eleven new tools listed under the server.

ChatGPT — the remote-only exception

ChatGPT supports MCP too, but with two constraints worth knowing before you spend time on it:

It only connects to remote servers over HTTPS (Streamable HTTP). A local npx command is invisible to it.
You need a Plus, Pro or Business plan and have to enable Developer mode — it lives under Settings → Security and login, flagged "elevated risk", which is fair: an unreviewed MCP server sees whatever the model sends it.

So the server has an --http mode, and you put a tunnel in front of it:

# terminal 1 — serve MCP over HTTP on localhost:3333
FIVEDOLLARFOOTBALL_API_KEY=fb_live_your_key npx -y football-api-mcp --http --token pick-a-secret

# terminal 2 — expose it (cloudflared shown; ngrok works the same way)
cloudflared tunnel --url http://localhost:3333

cloudflared prints a https://something.trycloudflare.com URL. In ChatGPT open Plugins in the sidebar, hit the + (Create app), choose Server URL, paste https://something.trycloudflare.com/mcp/pick-a-secret, set Authentication to No Auth, tick the acknowledgement, Create, then Connect. ChatGPT fetches the tool list immediately, so a typo in the URL fails right there rather than mid-conversation.

That --token is not decoration. ChatGPT can't attach custom headers to its requests, so a secret in the URL path is the only thing standing between "anyone who guesses the tunnel URL" and your API key. Pick something long.

Part 2: what it feels like to use

A few prompts that work on the free tier:

"What Premier League matches are on today, and what are the scores?"

The assistant calls get_fixtures (today, UTC), notices it needs a league id, calls search_leagues with "Premier League", then filters. You get a readable list with live scores, corner counts and cards.

"Show me the corner standings for the Premier League this season."

get_standings with type: "corner" — a table ranked by corners rather than points. This is the sort of question that's awkward on most football APIs and trivial here, because the data model has corner tables as a first-class thing.

"How did the 1x2 odds move for Arsenal vs Chelsea before kickoff?"

get_team_fixtures to find the fixture id, then get_odds_history with market: "1x2". Every recorded price tick comes back with a timestamp, and the assistant summarises the drift — which is a nicer experience than the Python loop in my previous post. Note that current odds need the $5 plan and the tick history the $25 one; the tool returns a clear insufficient_plan error otherwise, and the assistant explains it instead of hallucinating numbers.

What makes this work well is not the model — it's that each tool has a boring, precise description and a schema with every parameter documented. More on that below.

Part 3: how the server is built

The whole thing is under 300 lines of JavaScript on top of the official SDK. Source: github.com/5dollarfootball-api/football-api-mcp.

npm install @modelcontextprotocol/sdk fivedollarfootball zod

1. A server and one tool

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

export function buildServer(footballClient, { version = '0.0.0' } = {}) {
  const server = new McpServer({ name: 'football-api-mcp', version });

  server.registerTool('get_standings', {
    description: 'League table for a league and season. type "corner" and "card" return corner/card standings instead of points.',
    inputSchema: {
      league_id: z.number().int().describe('League id'),
      season: z.string().optional().describe('Season, e.g. "2026" or "26/27" (default: current)'),
      type: z.enum(['total', 'corner', 'card']).optional().describe('Table type (default total)'),
    },
  }, async ({ league_id, season, type }) => {
    const table = await footballClient.standings(league_id, { season, type });
    return { content: [{ type: 'text', text: JSON.stringify(table, null, 2) }] };
  });

  return server;
}

Three things to notice:

The client is injected, not constructed inside. That's what lets the test suite run an in-memory MCP client against a stubbed football client with no network.
The description is written for a model, not a human. "type 'corner' and 'card' return corner standings" is the sentence that makes the assistant reach for this tool when someone asks about corners. Vague descriptions produce wrong tool choices far more often than weak models do.
Every parameter has .describe(). The zod schema becomes the JSON schema the assistant sees. An undocumented optional parameter is one the model will either ignore or guess at.

2. Errors the model can act on

Ten tools in a row wrapping try/catch gets old, so there's one helper:

const run = (handler) => async (args) => {
  try {
    const payload = await handler(args ?? {});
    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
  } catch (err) {
    const bits = [err.message];
    if (err.code) bits.push(`code=${err.code}`);
    if (err.status) bits.push(`http=${err.status}`);
    if (err.requestId) bits.push(`request_id=${err.requestId}`);
    return { isError: true, content: [{ type: 'text', text: bits.join(' | ') }] };
  }
};

isError: true is the important bit. A thrown exception becomes a protocol error the assistant can't do much with; a tool result flagged as an error becomes text it reads and reasons about. That's why "this needs the $25 plan" turns into a helpful sentence rather than a crash, and why a request_id in the message means a user can paste it into a support email.

3. Transports: stdio for desktop apps, HTTP for everything else

The server object doesn't know how it's being talked to. The entry point picks a transport:

import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = buildServer(new Client(process.env.FIVEDOLLARFOOTBALL_API_KEY), { version });
await server.connect(new StdioServerTransport());

That's the whole stdio story — Claude Desktop and Cursor spawn the process and speak JSON-RPC over stdin/stdout.

For HTTP the SDK ships StreamableHTTPServerTransport. The simplest correct shape is stateless: build a fresh transport and server per request and let the SDK deal with the protocol.

import { createServer } from 'node:http';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';

createServer(async (req, res) => {
  if (new URL(req.url, 'http://x').pathname !== '/mcp') { res.writeHead(404).end(); return; }
  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
  await buildServer(footballClient, { version }).connect(transport);
  await transport.handleRequest(req, res);
}).listen(3333, '127.0.0.1');

sessionIdGenerator: undefined is what makes it stateless. You'd want sessions if tools held per-conversation state; for a read-only API wrapper they're overhead. This is also why a one-line --token path gate is enough security for a personal tunnel: there's no session to hijack, only requests to forward.

4. Test it without a network

The SDK has an in-memory transport pair, which turns "does my MCP server work" into a normal unit test:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';

const server = buildServer(stubFootballClient, { version: 'test' });
const client = new Client({ name: 'test', version: '0' });
const [ct, st] = InMemoryTransport.createLinkedPair();
await Promise.all([server.connect(st), client.connect(ct)]);

const { tools } = await client.listTools();          // 11 tools
const r = await client.callTool({ name: 'get_fixtures', arguments: { date: '2026-08-22' } });

The HTTP mode gets the same treatment with StreamableHTTPClientTransport pointed at a loopback port. A dozen tests, no API key, runs in under a second.

Small decisions that matter more than they look

Dates. get_fixtures takes YYYY-MM-DD and treats it as a UTC day. Anything else ("tonight", a locale-formatted date) is rejected with an error that states the expected format — and because it comes back as a tool result, the assistant simply retries with the right one.
Pagination belongs in the tool, not in the conversation. Results carry a pagination object and the description says so. Leave a model to infer paging from a raw array and it will sometimes loop, sometimes stop early, and occasionally loop forever.
Document the defaults. The odds tools take bookmaker slugs; the description says "(default bet365)". Without that line a model tends to call get_bookmakers first on every single odds question — a wasted round trip on each turn.
Read-only, and say so — in the protocol, not just the README. MCP tools carry annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). I skipped them at first, and ChatGPT's plugin view promptly labelled every tool PUBLIC WRITE / DESTRUCTIVE — its default for anything unannotated. One shared object fixed it:

  const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
  server.registerTool('get_standings', { description: '...', annotations: READ_ONLY, inputSchema: { ... } }, handler);

A test now asserts every registered tool carries it, so the next tool can't forget.

Wrapping up

Server: github.com/5dollarfootball-api/football-api-mcp · npm
API and key: 5dollarfootballapi.com · endpoint reference at /docs
The underlying JS client: fivedollarfootball on npm

If you wrap a different API the same way, I'd genuinely like to see it — the pattern above (inject the client, describe for the model, flag errors as results, keep HTTP stateless) has held up well and I'm curious where it breaks.

Questions or feedback? I'm happy to answer in the comments.

Tracking Football Odds Movement in Python — the Full Tick History, Not Just a Snapshot

John Ellis — Fri, 21 Aug 2026 08:01:09 +0000

Most football data APIs will tell you what the odds are right now. A few keep yesterday around. Almost none will show you the full journey — every price change from the moment a bookmaker opened the line to the final whistle.

That journey is where the interesting information lives. A 1X2 price drifting from 2.10 to 1.85 over three days tells you which way the money went. A corner line jumping half a goal at kickoff tells you how the market read the starting lineups. If you've ever wanted to study closing line value, detect steam moves, or just chart how a price evolved, you need ticks, not snapshots.

This tutorial builds a small odds-movement tracker in Python. We'll use 5DollarFootballAPI, which stores the complete tick history for every price it has recorded since 2014 — including corner and card lines, which most APIs don't carry at all.

Disclosure: I build that API. The technique here isn't specific to it — anything that serves you a price history works the same way. I'm using mine because I know exactly what's in it.

Setup

pip install fivedollarfootball

Grab an API key at 5dollarfootballapi.com. Worth knowing before you start, so nothing in this tutorial surprises you at the paywall:

Free (no card): fixtures, live scores, standings — enough for Step 1.
$5/mo: current odds, which is Step 2.
$25/mo: the tick history in Steps 3–5. Storing every price change for every market is the expensive part, and it's the tier this tutorial really needs.

from fivedollarfootball import Client

client = Client("fb_live_your_key")

Step 1: find today's matches

The fixtures endpoint defaults to a today-UTC kickoff window:

for match in client.fixtures():
    teams = match["teams"]
    print(match["id"], teams["home"]["name"], "vs", teams["away"]["name"], "-", match["status"])

Pick a fixture id from the output — ideally one a few hours from kickoff, so the market has had time to move.

Step 2: what do the odds look like right now?

odds = client.fixture_odds(FIXTURE_ID, bookmakers=["bet365"], market="1x2")
print(odds)

This is the snapshot every API gives you. Now for the part most of them can't do.

Step 3: pull the full movement history

history = client.odds_history(FIXTURE_ID, market="1x2", bookmaker="bet365")

for tick in history:
    print(tick["recorded_at"], tick["home"], tick["draw"], tick["away"])

Each tick carries the price at that moment, the running score, the match minute (None before kickoff), and a UTC timestamp:

{
  "minute": null,
  "home": 2.05,
  "draw": 3.40,
  "away": 3.60,
  "score": { "home": null, "away": null },
  "recorded_at": "2026-08-18T14:32:07+00:00"
}

The endpoint is paginated; iter_all walks every page for you:

ticks = list(client.iter_all(client.odds_history, fixture_id=FIXTURE_ID, market="1x2"))

Step 4: find the biggest pre-match moves

Let's answer a concrete question: which side did the market move against before kickoff?

prematch = [t for t in ticks if t["minute"] is None and t["home"] is not None]

if len(prematch) >= 2:
    opening, closing = prematch[0], prematch[-1]
    for side in ("home", "draw", "away"):
        move = (closing[side] - opening[side]) / opening[side] * 100
        arrow = "▼ backed" if move < 0 else "▲ drifted"
        print(f"{side:>5}: {opening[side]:.2f} → {closing[side]:.2f}  {arrow} {abs(move):.1f}%")

Sample output:

 home: 2.05 → 1.87  ▼ backed 8.8%
 draw: 3.40 → 3.55  ▲ drifted 4.4%
 away: 3.60 → 4.10  ▲ drifted 13.9%

A shortening price means money arrived on that side. Sum this over a season and you're measuring closing line value — the metric most serious bettors and modelers care about more than win rate.

Step 5: the same trick works on corner lines

This is the fun part. Corner totals move too, and that market is far less efficient than 1X2:

corner_ticks = list(client.iter_all(client.odds_history, fixture_id=FIXTURE_ID, market="corner"))

for tick in corner_ticks[-5:]:
    print(tick["recorded_at"], "line", tick["line"], "over", tick["over"], "under", tick["under"])

Line moves (say 9.5 → 10) are a stronger signal than price moves — a bookmaker only reprices the whole market when the flow forces them to.

Where to go from here

Store ticks in SQLite and chart them with matplotlib — one fixture is a few hundred rows at most.
Compare opening vs closing across a whole league season (league_fixtures + a loop).
Watch live: in-play ticks carry the match minute and running score, so you can line odds moves up against goals and red cards.

Full endpoint reference: 5dollarfootballapi.com/docs. The Python client is on GitHub and PyPI, and there's a matching Node.js client (GitHub, npm) if JavaScript is more your thing.

Questions or feedback? I'm happy to answer in the comments.