Content
# ⚽ Premier League MCP Server
A **Model Context Protocol (MCP) server** that gives Claude AI real-time access to football data — live scores, standings, and match info — with a focus on the **Premier League**, powered by the API-Football API.
> Built as part of the AI Superpowers challenge: giving Claude real tools to interact with the real world.
---
## 🤖 What can the AI do with this?
Once connected, Claude can:
- ⚽ **Fetch live football scores** from any ongoing match worldwide
- 📊 **Get league standings** for Premier League, La Liga, Serie A, Bundesliga, and more
- 🗣️ **Answer natural language questions** like *"Who's winning in the PL right now?"*
---
## 🛠️ Tech Stack
| Technology | Role |
|---|---|
| Python 3.11+ | Core language |
| [FastMCP](https://github.com/jlowin/fastmcp) | MCP server framework |
| httpx | Async HTTP requests |
| python-dotenv | API key management |
| API-Football (RapidAPI) | Football data source |
| Claude Desktop | MCP client for testing |
---
## 📁 Project Structure
```
pl-mcp-server/
├── tools/
│ ├── __init__.py
│ └── sports.py # API-Football logic
├── server.py # MCP server + tool definitions
├── .env # API keys (gitignored)
├── requirements.txt
└── README.md
```
---
## 🚀 Getting Started
### 1. Clone the repo
```bash
git clone https://github.com/nawfel-dahmani/pl-mcp-server.git
cd pl-mcp-server
```
### 2. Create virtual environment
```bash
python -m venv venv
# Windows
venv\Scripts\activate
# Mac/Linux
source venv/bin/activate
```
### 3. Install dependencies
```bash
pip install -r requirements.txt
```
### 4. Set up your API key
Create a `.env` file in the root:
```
RAPIDAPI_KEY=your_key_here
```
Get your free key at [rapidapi.com](https://rapidapi.com) → search **API-Football** → subscribe to the free plan.
### 5. Test the server
```bash
python server.py
```
If it runs silently with no errors — it works! ✅
---
## 🔌 Connect to Claude Desktop
1. Open Claude Desktop → Settings → Developer → **Edit Config**
2. Add this to the config file:
```json
{
"mcpServers": {
"pl-mcp-server": {
"command": "FULL_PATH_TO\\venv\\Scripts\\python.exe",
"args": ["FULL_PATH_TO\\server.py"]
}
}
}
```
3. Restart Claude Desktop
4. Look for **pl-mcp-server** in Settings → Developer with a 🟢 **running** badge
---
## 🧰 Available Tools
| Tool | Description | Parameters |
|---|---|---|
| `live_scores` | Get all live football matches right now | none |
| `standings` | Get league table | `league_id` (int), `season` (int) |
### Common League IDs
| League | ID |
|---|---|
| Premier League | 39 |
| La Liga | 140 |
| Serie A | 135 |
| Bundesliga | 78 |
| Ligue 1 | 61 |
---
## 💬 Example Prompts
Once connected to Claude Desktop, try:
```
"Are there any football matches happening right now?"
"Show me the Premier League standings for 2024"
"What's the La Liga table this season?"
```
---
## 📦 Requirements
```
mcp
httpx
python-dotenv
```
Install with:
```bash
pip install -r requirements.txt
```
---
## 📄 License
MIT License — see [LICENSE](LICENSE) for details.
