api-sports-mcp-server

yasha-dev1/api-sports-mcp-server

3.2

If you are the rightful owner of api-sports-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

MCP Server for api-sports.io provides a robust interface for accessing sports data through a model context protocol.

API-Sports MCP Server

Python Version MCP Tests

A Model Context Protocol (MCP) server that provides seamless integration with API-Sports football data API. This server enables AI assistants like Claude to access comprehensive football statistics, fixtures, team information, and more through standardized MCP tools.

Features

  • Teams Search: Search and retrieve detailed team information
  • Fixtures Management: Get match fixtures with comprehensive filtering options
  • Team Statistics: Access detailed team performance statistics
  • Smart Caching: Intelligent caching system to optimize API usage
  • Rate Limiting: Built-in rate limiting to respect API quotas
  • Comprehensive Logging: Structured logging with loguru for debugging and monitoring
  • Type Safety: Full type hints with Pydantic models
  • Async Support: Built on async/await for optimal performance

Installation

Prerequisites

  • Python 3.10 or higher
  • API-Sports API key (get one at api-sports.io)

Install from Source

# Clone the repository
git clone https://github.com/yasha-dev1/api-sports-mcp-server.git
cd api-sports-mcp-server

# Install in development mode
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

Running the Server

Command Line

# Run as a module
python -m mcp_server_api_sports

# Or use the installed script (after pip install -e .)
mcp-server-api-sports

# Or use the standalone script for development
python run_server.py

IntelliJ IDEA / PyCharm

For IntelliJ IDEA or PyCharm, you have several options:

  1. Run Configuration using run_server.py (Recommended for debugging):

    • Right-click on run_server.py in the project explorer
    • Select "Run 'run_server'"
    • This script handles imports correctly for IDE debugging

  2. Module Run Configuration:

    • Go to Run ā†’ Edit Configurations
    • Add a new Python configuration
    • Set "Module name" to: mcp_server_api_sports
    • Set working directory to project root
    • Add environment variable: API_SPORTS_API_KEY=your_key

  3. Script Path Configuration:

    • Go to Run ā†’ Edit Configurations
    • Add a new Python configuration
    • Set "Script path" to: run_server.py
    • Set working directory to project root
    • Add environment variable: API_SPORTS_API_KEY=your_key

Configuration

Environment Variables

Copy .env.example to .env and configure:

cp .env.example .env

Edit .env with your API key:

# Required
API_SPORTS_API_KEY=your_api_key_here

# Optional (defaults shown)
API_SPORTS_BASE_URL=https://v3.football.api-sports.io
LOG_LEVEL=INFO
CACHE_ENABLED=true
RATE_LIMIT_CALLS_PER_MINUTE=30
RATE_LIMIT_CALLS_PER_DAY=100

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "api-sports": {
      "command": "python",
      "args": ["-m", "mcp_server_api_sports.server"],
      "env": {
        "API_SPORTS_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available Tools

1. teams_search

Search for football teams with various filters.

Parameters:

  • id (integer): Team ID
  • name (string): Team name
  • league (integer): League ID
  • season (integer): Season year (YYYY)
  • country (string): Country name
  • code (string): 3-letter team code
  • venue (integer): Venue ID
  • search (string): Search string (min 3 characters)

Example Usage:

Search for Manchester United:
- By name: teams_search(name="Manchester United")
- By ID: teams_search(id=33)
- In Premier League 2023: teams_search(league=39, season=2023)

2. fixtures_get

Retrieve football fixtures (matches) with comprehensive filtering.

Parameters:

  • id (integer): Fixture ID
  • ids (string): Multiple fixture IDs (delimiter "-")
  • live (string): "all" or league IDs for live fixtures
  • date (string): Date in YYYY-MM-DD format
  • league (integer): League ID
  • season (integer): Season year (YYYY)
  • team (integer): Team ID
  • last (integer): Last N matches (max 99)
  • next (integer): Next N matches (max 99)
  • from (string): Start date (YYYY-MM-DD)
  • to (string): End date (YYYY-MM-DD)
  • round (string): Round name
  • status (string): Match status (NS, FT, etc.)
  • venue (integer): Venue ID
  • timezone (string): Timezone for dates

Example Usage:

Get fixtures for a team:
- Next 5 matches: fixtures_get(team=33, next=5)
- On specific date: fixtures_get(date="2024-01-15")
- Live matches: fixtures_get(live="all")

3. team_statistics

Get comprehensive statistics for a team in a specific league and season.

Required Parameters:

  • league (integer): League ID
  • season (integer): Season year (YYYY)
  • team (integer): Team ID

Optional Parameters:

  • date (string): Date for statistics snapshot (YYYY-MM-DD)

Example Usage:

Get Manchester United's Premier League 2023 stats:
team_statistics(league=39, season=2023, team=33)

Usage Examples

With Claude Desktop

Once configured, you can ask Claude:

  • "Find information about Real Madrid"
  • "Show me the next 5 matches for Liverpool"
  • "Get Manchester United's statistics for the 2023 Premier League season"
  • "What matches are happening today?"
  • "Show me Arsenal's recent form"

Programmatic Usage

import asyncio
from mcp_server_api_sports.services import ApiSportsService, CacheService
from mcp_server_api_sports.tools import TeamsTool, FixturesTool

async def main():
    # Initialize services
    api_service = ApiSportsService()
    cache_service = CacheService()
    
    # Create tools
    teams_tool = TeamsTool(api_service, cache_service)
    
    # Search for a team
    result = await teams_tool.search_teams(name="Barcelona")
    print(result)

asyncio.run(main())

API Response Format

All tools return JSON responses with consistent structure:

{
  "teams": [...],  // or "fixtures", "statistics"
  "count": 10,
  "request_id": "uuid-here"
}

Error responses:

{
  "error": "Error message",
  "request_id": "uuid-here"
}

Caching

The server implements intelligent caching to reduce API calls:

  • Teams: Cached for 24 hours
  • Completed Fixtures: Cached permanently
  • Upcoming Fixtures: Cached for 1 hour
  • Statistics: Cached for 1 hour
  • Live Fixtures: Not cached

Cache can be disabled by setting CACHE_ENABLED=false in your .env file.

Rate Limiting

Built-in rate limiting protects against exceeding API quotas:

  • Configurable calls per minute/day
  • Automatic retry with exponential backoff
  • Queue system for burst requests
  • Graceful handling of rate limit errors

Logging

Comprehensive logging powered by loguru:

  • Structured JSON or text format
  • Automatic log rotation
  • Performance metrics
  • Request tracing with IDs
  • Separate error log file

Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=mcp_server_api_sports

# Run specific test file
pytest tests/test_tools/test_teams.py

Linting and Type Checking

# Run linting
ruff check mcp_server_api_sports tests

# Run type checking
mypy mcp_server_api_sports

# Format code
black mcp_server_api_sports tests
isort mcp_server_api_sports tests

Project Structure

api-sports-mcp-server/
ā”œā”€ā”€ mcp_server_api_sports/
ā”‚   ā”œā”€ā”€ __init__.py
ā”‚   ā”œā”€ā”€ server.py           # Main MCP server
ā”‚   ā”œā”€ā”€ config.py           # Configuration management
ā”‚   ā”œā”€ā”€ logger.py           # Loguru logging setup
ā”‚   ā”œā”€ā”€ services/
ā”‚   ā”‚   ā”œā”€ā”€ api_sports_service.py  # API client
ā”‚   ā”‚   ā””ā”€ā”€ cache_service.py       # Caching layer
ā”‚   ā”œā”€ā”€ tools/
ā”‚   ā”‚   ā”œā”€ā”€ teams.py        # Teams tool
ā”‚   ā”‚   ā”œā”€ā”€ fixtures.py     # Fixtures tool
ā”‚   ā”‚   ā””ā”€ā”€ statistics.py   # Statistics tool
ā”‚   ā””ā”€ā”€ models/
ā”‚       ā””ā”€ā”€ api_models.py   # Pydantic models
ā”œā”€ā”€ tests/
ā”‚   ā”œā”€ā”€ conftest.py         # Test fixtures
ā”‚   ā”œā”€ā”€ test_service.py     # Service tests
ā”‚   ā””ā”€ā”€ test_tools/         # Tool tests
ā””ā”€ā”€ pyproject.toml          # Project configuration

Troubleshooting

Common Issues

  1. API Key Error: Ensure your API key is correctly set in the environment
  2. Rate Limiting: Adjust RATE_LIMIT_CALLS_PER_MINUTE if hitting limits
  3. Cache Issues: Clear cache by restarting the server or disable with CACHE_ENABLED=false
  4. Connection Errors: Check your internet connection and API-Sports service status

Debug Mode

Enable debug logging for more details:

LOG_LEVEL=DEBUG
LOG_FORMAT=text  # Easier to read for debugging

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass
  5. Submit a pull request

License

MIT License - see file for details.

Acknowledgments

Support

For issues, questions, or suggestions: