Command Palette

Search for a command to run...

UnylyUnyly
Весь каталог

SofaScore

БесплатноНе проверен

An MCP server that answers football questions with interactive widgets, centered on the 2026 FIFA World Cup using SofaScore API data.

TejasQавтор: TejasQ
GitHubEmbed

Описание

An MCP server that answers football questions with interactive widgets, centered on the 2026 FIFA World Cup using SofaScore API data.

README

A ChatGPT App (OpenAI Apps SDK / MCP-UI) that answers football questions with rich, interactive widgets — centered on the 2026 FIFA World Cup (48 teams, hosted by the USA, Canada & Mexico) while still handling general football.

It's an MCP server (Streamable HTTP) whose tools each render a React widget inside ChatGPT via the openai/outputTemplate + text/html+skybridge pattern. Data comes from SofaScore's public JSON API.

World Cup hub

Match detail Knockout bracket Standings (light theme)

What it does

Tool What it answers Widget
world_cup Anything about the World Cup — groups, knockout bracket, live/upcoming matches. Views: overview · groups · knockout · matches. Tabbed World Cup hub with a knockout bracket
list_matches "What football is on today?", live scores, a date's fixtures, one competition's matches. Scoreboard grouped by tournament, live pulse
get_match Full detail of one match: score, goal/card timeline, team stats, momentum. Match page with momentum chart & stat bars
get_standings A competition's league table (by name or SofaScore id). Standings table (multi-group aware)
search_football Find a team / player / competition / manager by name. Result list that drills into the other tools

Widgets are theme-aware (light/dark follow window.openai.theme), use SofaScore crest/flag images with an initials fallback, and are interactive — match rows and search results call back into other tools via window.openai.callTool.

Architecture

src/
  server.ts            Express + StreamableHTTPServerTransport (POST /mcp, /health)
  mcp.ts               McpServer factory: server instructions + resources + tools
  resources.ts         registers each built widget as a ui:// text/html+skybridge resource
  sofascore/           data layer: SofaScore client (browser headers, TTL cache,
                       optional proxy, server-side image fetch) + ESPN fallback
                       source, both behind one FootballApi interface (provider.ts,
                       fallback.ts, espn.ts); raw→structuredContent mappers, WC logic
api/index.ts           Vercel serverless entry (re-exports the Express app)
  shared/shapes.ts     structuredContent types shared by server + widgets
  tools/               list_matches · get_match · get_standings · world_cup · search_football
widgets/               React sources (built per-widget to one self-contained HTML)
  shared/              window.openai bridge + hooks, theme, reusable components
scripts/               build-widgets · smoke (wiring) · screenshots (visual)
test/fixtures/         demo SofaScore responses for offline runs

Each widget is built by vite + vite-plugin-singlefile into a single dist/widgets/<name>/index.html (JS + CSS inlined), which is served verbatim as the skybridge resource — no separate asset host needed.

Images (why they route through this server)

Team/tournament/player crests can't be loaded straight from api.sofascore.com inside the ChatGPT Apps sandbox: the iframe's CSP (img-src) blocks the host, and SofaScore itself 403s the referer-less cross-origin request. So the server exposes an image proxy and the widgets point at it instead:

GET /img/team/:id          → https://api.sofascore.com/api/v1/team/:id/image
GET /img/tournament/:id     → …/unique-tournament/:id/image
GET /img/player/:id         → …/player/:id/image
GET /img/flag/:alpha2       → …/img/flags/:alpha2.png

Only these allow-listed shapes are proxied. resources.ts injects window.__SOFA_BASE__ (from PUBLIC_BASE_URL) into each widget's <head>, and widgets/shared/img.ts builds ${__SOFA_BASE__}/img/... URLs from it. If PUBLIC_BASE_URL is unset (e.g. local MCP Inspector) the widgets fall back to loading images directly from SofaScore.

Run it

npm install
npm run dev          # builds widgets, then starts the server on :3000 (POST /mcp)

Point an MCP client at http://localhost:3000/mcp, or run with SOFA_MOCK=1 to serve the bundled fixtures instead of the live API:

SOFA_MOCK=1 npm run dev

Environment variables

Variable Purpose
PORT HTTP port (default 3000).
SOFA_MOCK 1 serves the bundled fixtures instead of the live API — no network needed.
PUBLIC_BASE_URL Public origin this server is reachable at (e.g. https://sofa.example.com). Needed for the image proxy so crests load inside the ChatGPT sandbox. On Vercel it defaults to the deployment URL. Unset elsewhere → widgets load images directly.
SOFA_PROXY Outbound HTTP(S) forward proxy for all SofaScore fetches (data + images). Point at a residential / unblocked proxy to defeat the Varnish/IP block. Falls back to HTTPS_PROXY.
ESPN_ONLY 1 skips SofaScore entirely and serves everything from the ESPN fallback. Handy on hosts where SofaScore is always blocked (avoids the per-request probe + cooldown). 
# Live, behind a proxy, with images proxied through this origin:
PUBLIC_BASE_URL=https://sofa.example.com \
SOFA_PROXY=http://user:pass@proxy-host:port \
npm run dev

Add it to ChatGPT (Developer Mode)

  1. Expose the server over HTTPS (e.g. ngrok http 3000).
  2. In ChatGPT → Settings → Connectors → Advanced → Developer mode, add a new connector pointing at https://<your-tunnel>/mcp.
  3. Ask: "Show me the World Cup group standings" or "What football is live right now?" — the matching widget renders inline.

Deploy to Vercel

The repo is Vercel-ready: api/index.ts re-exports the Express app as a single serverless function and vercel.json rewrites every path to it.

vercel deploy        # first run links the project; prod: `vercel --prod`
  • Build — vercel.json's buildCommand runs npm run build, bundling the five widget HTML files into dist/widgets/; includeFiles ships them with the function (the resource loader also resolves them from process.cwd()).
  • Base URL — PUBLIC_BASE_URL defaults to the deployment's VERCEL_URL, so the image proxy works with no extra config. Set it explicitly for a custom domain.
  • Data — ESPN fallback means live data works immediately. To keep SofaScore primary, add SOFA_PROXY in the Vercel project's Environment Variables; to drop it, set ESPN_ONLY=1.
  • Connector URL — point ChatGPT at https://<deployment>/mcp.

The function's maxDuration is 30s to cover ESPN's multi-league fan-out; the landing page at / is served statically from public/.

Verify

All verification runs offline (no live network needed):

npm run typecheck        # server + widgets typecheck
npm run build:widgets    # bundle the 5 self-contained widget HTML files
npm run verify           # build + wiring smoke test + Playwright screenshots
  • scripts/smoke.ts boots the server with fixtures, connects an in-process MCP client, and asserts every tool's openai/outputTemplate resolves to a registered ui:// resource with non-empty structuredContent.
  • scripts/screenshots.ts renders each built widget with the real server output (Chromium, window.openai set exactly like the host) into .artifacts/shots/.

Note on data & this environment

The primary source is the live SofaScore API (api.sofascore.com), used with browser-like headers. Its edge (Varnish) returns 403 to datacenter IPs and flagged TLS fingerprints regardless of headers — so a cloud host, CI runner, or this sandbox often can't reach it. This is an egress-IP block, not a missing header.

So the server falls back to ESPN's public soccer API automatically. Every data source sits behind one FootballApi interface; FallbackApi tries SofaScore first (honouring SOFA_PROXY) and, on any 403 / timeout / empty result, transparently serves the same request from ESPN — mapped into the exact same shapes, so tools and widgets never know the difference. ESPN is reachable from blocked networks, covers the FIFA World Cup + the top-5 European leagues, and needs no API key. Result: live data flows out of the box, no proxy required. Team crests come from a.espncdn.com via the same image proxy.

Ways to control the source:

  1. Default — SofaScore → ESPN fallback. Just works anywhere.
  2. ESPN_ONLY=1 — skip SofaScore entirely (best on always-blocked hosts).
  3. SOFA_PROXY=<url> — give SofaScore a residential / unblocked egress so it stays primary (see below).
  4. SOFA_MOCK=1 — bundled fixtures, fully offline (dev / tests / demos).

The World Cup season resolves dynamically (not hardcoded).

Getting a proxy endpoint

SOFA_PROXY takes a standard http(s)://[user:pass@]host:port URL. What you need is an IP SofaScore hasn't blocked — in practice a residential or mobile proxy (datacenter proxies are usually blocked too). Options:

  • Managed residential proxy providers — Bright Data, Oxylabs, Smartproxy, IPRoyal, Soax, etc. Sign up, create an endpoint, and they give you a http://user:pass@gateway:port URL. Paste it into SOFA_PROXY. Cheapest to start; billed per GB (crest images are tiny, JSON is tiny — usage is low).
  • Your own home/residential IP — run the server on a machine at home, or tunnel through one (e.g. a small box on a home connection running ngrok / tailscale + a forward proxy like tinyproxy or squid). Free if you already have the hardware.
  • A cheap VPS on a residential-friendly ASP — some VPS/edge providers hand out IP ranges SofaScore doesn't block; try a curl from the box first (below).

Test any candidate before wiring it in:

curl -x "http://user:pass@proxy-host:port" \
  -H "User-Agent: Mozilla/5.0" -H "Referer: https://www.sofascore.com/" \
  -o /dev/null -w "%{http_code}\n" \
  https://api.sofascore.com/api/v1/sport/football/events/live

200 → set that URL as SOFA_PROXY. 403 → that IP is blocked too; try another.

Not affiliated with SofaScore; uses their public endpoints for informational use.

from github.com/TejasQ/sofascore-mcp

Установка SofaScore

У этого сервера нет опубликованного пакета — он собирается из исходников. Открой репозиторий и следуй инструкции в README.

▸ github.com/TejasQ/sofascore-mcp

FAQ

SofaScore MCP бесплатный?

Да, SofaScore MCP бесплатный — установка в пару кликов через Unyly без оплаты.

Нужен ли API-ключ для SofaScore?

Нет, SofaScore работает без API-ключей и переменных окружения.

SofaScore — hosted или self-hosted?

Доступен hosted-вариант: Unyly запускает сервер в облаке, локальная установка не обязательна.

Как установить SofaScore в Claude Desktop, Claude Code или Cursor?

Открой SofaScore на unyly.org, выбери вкладку своего клиента (Claude Desktop, Claude Code, Cursor) и нажми Install — конфиг сгенерируется автоматически, без правки JSON.

Похожие MCP

GitHub

PRs, issues, code search, CI status

GitHubавтор: GitHub

Filesystem

Secure file operations with configurable access controls.

автор: Community

Memory

Knowledge graph-based persistent memory system.

автор: Community

Template MCP Server

A CLI tool to create a new Model Context Protocol server project with TypeScript support, dual transport options, and an extensible structure

mcpdotdirectавтор: mcpdotdirect

Compare SofaScore with

SofaScorevsGitHubSofaScorevsFilesystemSofaScorevsMemorySofaScorevsTemplate MCP Server

Не уверен что выбрать?

Найди свой стек за 60 секунд

Автор?

Embed-бейдж для README

Похожее

Все в категории development