omerzzeybek9/MCP-Server-with-Football-API

Football — TheSportsDB MCP Server

A TheSportsDB-backed MCP (Multi-Client-Plugin) server exposing football data as MCP tools.

Overview

This project exposes TheSportsDB API through an MCP server implemented in . The server registers tools such as team search, player lists and event details that can be consumed by MCP clients.

Requirements

• Python >= 3.10 (see )
• Dependencies are declared in

Installation

1. Create and activate a virtual environment: python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate

2. Install the package in editable mode: pip install -e .

Configuration

• Environment variables:

  • THESPORTSDB_API_KEY — TheSportsDB API key (default in config: "123")
  • USER_AGENT — optional User-Agent header value

• The included VS Code MCP launch configuration is . It runs: uv run main.py

Running

From repository root: uv run main.py

The server is started in stdio transport via mcp.run(transport="stdio") in .

Available MCP tools (registered in main.py)

• Team search:
• List players:
• Upcoming events:
• Past events:
• List leagues:
• Full event details (concurrent lookups):
• Raw API GET:

Helper functions and internals:

• HTTP helper:
• URL builder:
• MCP server instance:
• MCP server class reference:

Example usage

Invoke search_teams from an MCP client and pass a team name. See tool signatures in .

Development notes

• The MCP server instance is created as using .
• Error responses are normalized and formatted by .
• Concurrent event details are fetched with asyncio.gather inside .

Files of interest

• Server code:
• Project metadata:
• VSCode MCP runner:
• Python version pin:
• Git ignore:
• Lock file:

Contributing

Open issues for bugs or feature requests. Pull requests should include tests or a description of manual verification steps.