Skip to main content
Glama
kickmesh-mcp

kickmesh-mcp

by si-essence

kickmesh-mcp (Kickmesh MCP connector)

MCP server for API-Football v3 (https://v3.football.api-sports.io). TypeScript, official @modelcontextprotocol/sdk, stdio + Streamable HTTP.

Setup

npm install && npm run build
export API_FOOTBALL_KEY=your_key   # free key: https://dashboard.api-football.com
npm start                 # stdio
npm run start:http        # Streamable HTTP at http://localhost:3000/mcp (PORT to change), /health
npm test                  # mocked tests, no key needed

The free API-Football plan covers seasons 2022–2024 only. Live and current-season data (plus next/last match filters) needs your own paid API-Football plan.

Claude Desktop / any stdio client:

{ "mcpServers": { "kickmesh-mcp": { "command": "node", "args": ["/absolute/path/to/kickmesh-mcp/dist/index.js"], "env": { "API_FOOTBALL_KEY": "..." } } } }

Docker: docker build -t kickmesh-mcp . && docker run -p 3000:3000 -e API_FOOTBALL_KEY=... kickmesh-mcp

Related MCP server: fotmob-mcp

Tools

live_scores, fixtures, standings, team_stats, player_stats, lineups, events, transfers, injuries, odds, predictions, search_teams, search_leagues, api_budget (local usage, no API call).

Football headlines (public RSS, no API-Football quota): latest_news, news_search, list_sources.

Football news

latest_news returns recent items from free public feeds. Optional filters: source, team, league, keyword, limit (default 20, max 50). news_search takes a query plus optional source and limit. list_sources lists each feed's name, URL, homepage, status, last fetch time, and item count.

Each item has title, summary, source, publishedAt (ISO), link, and tags (teams, leagues). The summary is the feed <description> or Atom <summary> only: HTML stripped, at most two sentences, trimmed to about 300 characters. Article pages are never downloaded, and content:encoded / Atom <content> is ignored.

Feeds (checked live; User-agent: * does not disallow these paths):

The in-memory cache refreshes on an unref'd 12-minute interval while the process is running, and again on demand when a news tool is called and the cache is stale. Items are deduped by normalized link (lowercase host, no query, hash, or trailing slash) and by normalized title. A feed that fails does not drop the others; its last good items stay available and list_sources shows the error. Team and league tags come from a club/competition dictionary (aliases, word boundaries). Names already sitting in the API-Football response cache are included when they match, without a new API call. News fetches use plain fetch and do not touch the daily or per-minute budget.

npm run check:news (after npm run build) fetches each feed once and prints ok/fail and item counts.

Caveats: Sky's 12040 feed is general Sky Sports news, so non-football items appear. Tagging can miss a club or match the wrong one. Identical headlines collapse even when the stories differ. Publisher terms still apply — BBC and Guardian robots/terms restrict scraping, AI/RAG, and commercial reuse; ESPN and CBS disallow some AI crawler user-agents. This server is for local reading of the public feed documents. The cache resets on restart.

Caching & rate limits (free plan: 100 req/day)

  • In-memory TTL cache per endpoint: live 30s, events 60s, fixtures 5m, lineups 10m, odds 30m, standings/stats/players/injuries/predictions 1h, teams/leagues/transfers 24h. Cache hits cost no budget.

  • Daily budget counter (default 100, resets 00:00 UTC, synced from x-ratelimit-requests-remaining), and per-minute limit (default 10).

  • When exhausted, tools return isError with a [budget] message; cached data is still served.

  • Env overrides: API_FOOTBALL_DAILY_LIMIT, API_FOOTBALL_PER_MINUTE_LIMIT, API_FOOTBALL_BASE_URL, MCP_TRANSPORT=http, PORT.

  • News RSS refresh is separate from that budget (12 minutes, in-memory).

  • Counters and cache are in-memory; they reset on restart (the header sync corrects the daily count on the next call).

License

MIT, see LICENSE. This is an independent, unofficial connector and is not endorsed by the Kickmesh project or its owners.

Available Tools

17 tools
api_budgetA

Show local daily/minute request budget usage (no API call)

Inputs: no named parameters.

eventsC

Events (goals, cards, subs) for a fixture

Inputs: fixture (required).

fixturesC

Fixtures by date, league, team, season (at least one filter)

Inputs: to, date, from, last, +6 more.

injuriesC

Injuries by league/season, team, fixture, or date

Inputs: date, team, league, season, +1 more.

latest_newsA

Latest headlines from configured public football RSS feeds. Optional filters: source, team, league, keyword, limit. Uses feed descriptions only and does not spend the API-Football budget.

Inputs: team, limit, league, source, +1 more.

lineupsC

Lineups for a fixture

Inputs: fixture (required).

list_sourcesA

List configured football RSS feeds with homepage, status, last fetch time, and item count.

Inputs: no named parameters.

live_scoresB

Live fixtures in progress, optionally filtered by league ids

Inputs: leagues.

oddsD

Pre-match odds

Inputs: bet, date, league, season, +2 more.

player_statsC

Player statistics by player id, team, or league + search

Inputs: season (required), id, page, team, +2 more.

predictionsC

Predictions for a fixture

Inputs: fixture (required).

search_leaguesA

Search leagues/cups by name, or list by country/season. With a query, country/season are filtered client-side

Inputs: query, season, country.

search_teamsA

Search teams by name (min 3 alphanumeric chars); optional country filter applied client-side

Inputs: query (required), country.

standingsC

League standings

Inputs: league (required), season (required).

team_statsC

Team statistics for a league season

Inputs: team (required), league (required), season (required).

transfersC

Transfers by player or team

Inputs: team, player.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 17 tools

    Disambiguation4/5

    Most tools target clearly distinct resources (fixtures, standings, lineups, events, odds, predictions, injuries, transfers), so selection is straightforward. The main overlap risks are live_scores vs. fixtures (in-progress vs. date-filtered) and latest_news vs. news_search (fetch-latest vs. query-cache), but the descriptions do enough to separate them.

    Naming Consistency3/5

    Everything is snake_case, but the conventions are mixed: many tools are bare resource nouns (fixtures, standings, odds, events) while others use verb prefixes/suffixes (search_teams, search_leagues, list_sources, news_search, live_scores, latest_news). The search_* prefix vs. news_search suffix inconsistency in particular makes the pattern less predictable than it could be.

    Tool Count4/5

    At 17 tools the surface is on the heavy side, but the domain genuinely spans match data, team/player stats, odds, predictions, injuries/transfers, plus a separate news subsystem, so each tool maps to a real data endpoint. Nothing feels like filler, though a couple of news tools could arguably be folded together.

    Completeness4/5

    The surface covers the core football-data lifecycle well: discovery (search_teams/search_leagues), fixtures/live, standings, team and player stats, lineups, events, transfers, injuries, odds and predictions, plus news and a budget meter. Notable gaps are head-to-head comparison (a standard API-Football endpoint and a natural companion to predictions) and venue/coach or season/round listing endpoints.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides programmatic access to comprehensive football statistics and live match data via API-Football, enabling applications to retrieve league standings, team fixtures, player statistics, and real-time match events.
      6
      -
    • F
      license
      B
      quality
      D
      maintenance
      Enables access to live FotMob football data for fixture lookup, team and player research, match details, lineups, league discovery, and search-based entity lookup.
      7
      11
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language querying of football/soccer data via the API-Football service, providing access to leagues, teams, players, fixtures, standings, and statistics.
      2
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Access football (soccer) data including competitions, matches, standings, and team details via the Football-Data.org API.
      95 npm
      2
      MIT