API Football MCP

API-足球MCP服务器

一个通过API-Sports的API-Football v3提供英超联赛数据的模型上下文协议（MCP）服务器。该服务器采用TypeScript编写，具有严格的类型检查、强大的错误处理能力，以及为代理工作流设计的合理缓存机制。

特点/功能

• 历史覆盖范围英超联赛历史数据（许多终点指标通常涵盖2002年至今；部分工具在数据可得的情况下支持1992年及以后的数据）
• 实时数据实时比赛赛事、当前积分榜及赛程信息
• 智能缓存带TTL的LRU缓存以实现最佳性能
• 速率限制内置速率限制跟踪和指数退避机制
• MCP集成原生模型上下文协议对大型语言模型（LLM）集成的支持
• TypeScript严格的TypeScript配置（禁用未检查的索引访问，精确可选属性类型）

MCP 工具

数据覆盖说明

• 通过API‑Football v3获取的英格兰足球超级联赛历史数据，通常从2002赛季开始即可获取。更早的赛季（2002年之前）可能不完整或无法获取，具体取决于特定的接口端点。
• 如果您需要特定赛季的球队，请使用 season 和，与，带有 get_team （内部使用 /players （端点）或CLI（命令行界面） --endpoint squad team= season= 助手，它会汇总所有页面并打印出一个不包含图片URL的简洁表格。
• 支持固定查询 round 以……的形式 "Regular Season - N" 除了……之外 season， date，和 from/to。

安装

先决条件

• Node.js 22及以上版本
• pnpm 包管理器
• API‑Football API密钥来自 API‑Sports

设置

1. 克隆仓库

   git clone https://github.com/MarvDann/api-football-mcp.git
   cd api-football-mcp

1. 安装依赖项

   pnpm install

1. 配置环境

   # Set your API key as an environment variable
   export API_FOOTBALL_KEY=your_api_key_here

   # Or create a .env file
   echo "API_FOOTBALL_KEY=your_api_key_here" > .env

1. 构建项目

   pnpm run build

使用方法

作为MCP服务器

主要用例是作为大型语言模型（LLM）集成的机器通信协议（MCP）服务器：

# Start the MCP server
pnpm start

# Or run directly
node dist/server.js

MCP客户端配置

以下是支持MCP的流行代理的示例配置。所有示例均通过stdio启动此服务器。请将${API_FOOTBALL_KEY}替换为您的密钥或依赖您的shell环境。

• Claude 桌面版（claude_desktop_config.json）：

{
  "mcpServers": {
    "api-football": {
      "command": "node",
      "args": ["dist/server.js"],
      "env": {
        "API_FOOTBALL_KEY": "${API_FOOTBALL_KEY}",
        "NODE_ENV": "production",
        "LOG_TO_FILE": "true",
        "LOG_DIR": "./logs",
        "LOG_ROTATE_INTERVAL": "1d"
      }
    }
  }
}

• Claude 配置（VS Code 的 settings.json）：

{
  "claudeCode.mcpServers": [
    {
      "name": "api-football",
      "command": "node",
      "args": ["dist/server.js"],
      "env": {
        "API_FOOTBALL_KEY": "${API_FOOTBALL_KEY}",
        "NODE_ENV": "production",
        "LOG_TO_FILE": "true",
        "LOG_DIR": "./logs"
      }
    }
  ]
}

• 光标（设置 JSON）：

{
  "mcpServers": {
    "api-football": {
      "command": "node",
      "args": ["dist/server.js"],
      "env": {
        "API_FOOTBALL_KEY": "${API_FOOTBALL_KEY}",
        "NODE_ENV": "production",
        "LOG_TO_FILE": "true",
        "LOG_DIR": "./logs"
      }
    }
  }
}

• 双子座（支持CLI/桌面MCP）：

{
  "mcpServers": {
    "api-football": {
      "command": "node",
      "args": ["dist/server.js"],
      "env": {
        "API_FOOTBALL_KEY": "${API_FOOTBALL_KEY}",
        "NODE_ENV": "production",
        "LOG_TO_FILE": "true",
        "LOG_DIR": "./logs"
      }
    }
  }
}

• Codex CLI（本地代理）：

{
  "mcpServers": {
    "api-football": {
      "command": "node",
      "args": ["dist/server.js"],
      "env": {
        "API_FOOTBALL_KEY": "${API_FOOTBALL_KEY}",
        "NODE_ENV": "production",
        "LOG_TO_FILE": "true",
        "LOG_DIR": "./logs"
      }
    }
  }
}

代理可用的工具包括：获取排名 (get_standings)、获取赛程 (get_fixtures)、获取球队信息 (get_team)、获取球员信息 (get_player)、获取球队阵容 (get_squad)、获取比赛进球 (get_match_goals)、获取比赛事件 (get_match_events)、获取直播比赛 (get_live_matches)、搜索球队 (search_teams)、搜索球员 (search_players)、获取速率限制 (get_rate_limit)。

命令行界面工具（CLI Tools）

服务器管理

# Start server with custom settings
node dist/cli/server.js start --log-level debug --verbose

# Check server health
node dist/cli/server.js health

# Validate configuration
node dist/cli/server.js validate --dry-run

# List available MCP tools
node dist/cli/server.js tools

# Show cache statistics
node dist/cli/server.js cache --verbose

API 客户端命令行界面

# Get current season standings
node dist/cli/api-client.js --endpoint standings

# Get fixtures for a specific date range
node dist/cli/api-client.js --endpoint fixtures season=2023 from=2023-01-01 to=2023-01-31

# Search for a team (table output includes venue details)
node dist/cli/api-client.js --endpoint teams search="Arsenal"

# Get detailed team info for a specific season
node dist/cli/api-client.js --endpoint team id=42 season=2024

# Get player information
node dist/cli/api-client.js --endpoint player id=276 --format table

# Get a club's full season squad (multi-page fetch, compact table without photo URLs)
node dist/cli/api-client.js --endpoint squad team=33 season=2025

# Get goal events for a fixture
node dist/cli/api-client.js --endpoint goals fixture=123456 --format table

# Check rate limit status
node dist/cli/api-client.js --endpoint rate-limit --format table

缓存管理命令行界面（CLI）

# View cache statistics
node dist/cli/cache.js stats --format table

# List cached keys
node dist/cli/cache.js keys

# Find keys by pattern
node dist/cli/cache.js find "standings:*"

# Clear cache
node dist/cli/cache.js clear

# Get specific cached value
node dist/cli/cache.js get "standings:2023"

配置

环境变量

缓存策略

服务器根据数据类型使用不同的缓存TTL（生存时间）值：

• 历史数据 （过往季节）：24小时
• 当前赛季数据5分钟
• 实时比赛数据30秒
• 静态数据 （队伍，球员）：1小时

发展

脚本

# Development
pnpm run dev          # Watch mode with hot reload
pnpm run build        # Build TypeScript
pnpm run lint:check   # Run ESLint (no fix)
pnpm run lint         # Run ESLint with --fix
pnpm run test         # Run all tests

# Offline test suite (no real API calls)
pnpm run test:offline   # unit + contract + performance (mocked)

# Online tests (may hit API-Football; respect rate limits)
pnpm run test:online

# Run specific categories
pnpm run test:unit
pnpm run test:contract
pnpm run test:performance
pnpm run test:integration

# Type checking
pnpm run check-types  # Type check without emitting

项目结构

src/
├── models/           # TypeScript interfaces
│   ├── league.ts     # League data models
│   ├── team.ts       # Team and venue models
│   ├── player.ts     # Player and statistics models
│   ├── fixture.ts    # Match and fixture models
│   ├── standing.ts   # League standings models
│   └── ...
├── lib/
│   ├── api-client/   # API-Football HTTP client
│   ├── cache/        # LRU cache with TTL
│   ├── tools/        # MCP tool implementations
│   └── server/       # Structured logger + helpers
├── services/         # Business logic layer
├── cli/              # Command-line interfaces
├── config.ts         # Configuration management
└── server.ts         # MCP server entry (built to dist/server.js)

tests/
├── unit/             # Unit tests
├── integration/      # Integration tests
├── contract/         # API contract tests
└── performance/      # Performance tests

测试

该项目遵循测试驱动开发（TDD）的方法：

# Run all tests
pnpm test

# Run specific test categories
pnpm run test:unit
pnpm run test:integration
pnpm run test:contract
pnpm run test:performance

# Run tests in watch mode
# Offline suite (does not require API key)
pnpm run test:offline

# Online tests (require API key, respect vendor rate limits)
pnpm run test:online

代码质量

• ESLint（埃斯利恩特，一种JavaScript代码静态分析工具）标准风格（不使用分号，两个空格）。在测试中，对未使用的变量和非空断言的要求较为宽松。在源代码中，对以（此处原文未完整，假设后续为某前缀或关键字）开头的未使用参数的要求较为宽松 _ 被允许。
• TypeScript严格模式已启用
• Vitest带有覆盖率的测试框架
• 自动格式化在VS Code中保存时自动修复ESLint

API 参考文档

数据模型

团队

interface Team {
  id: number
  name: string
  code: string
  country: string
  founded: number
  national: boolean
  logo: string
}

玩家

interface Player {
  id: number
  name: string
  firstname: string
  lastname: string
  age: number
  birth: {
    date: string
    place: string
    country: string
  }
  nationality: string
  height: string
  weight: string
  injured: boolean
  photo: string
}

Fixture（在中文中，根据上下文可翻译为“装置”、“设施”、“设备”或“配件”等，具体含义需结合语境确定）

interface Fixture {
  id: number
  referee: string
  timezone: string
  date: string
  timestamp: number
  periods: {
    first: number
    second: number
  }
  venue: {
    id: number
    name: string
    city: string
  }
  status: {
    long: string
    short: string
    elapsed: number
  }
}

速率限制

API-Football服务有速率限制。服务器会自动处理：

• 读取速率限制头部信息 来自API响应
• 实现指数退避算法 当达到限制时
• 请求队列 遵守速率限制
• 缓存响应 为了最小化API调用

速率限制状态可以通过以下方式监控：

node dist/cli/api-client.js --endpoint rate-limit --format table

错误处理

服务器提供了全面的错误处理功能：

• MCP 错误代码标准的MCP错误响应
• API故障优雅地处理API错误
• 缓存回退机制当API不可用时，提供缓存数据
• 请求验证API调用前的参数验证
• 结构化日志记录详细的错误日志记录，用于调试

演出

基准（或标准）

• 缓存命中\=3.5秒）

- 处理429错误，并在建议的延迟后重试 - 建议使用季节性过滤器以减少有效载荷大小