Content
# Betfair API MCP Server
This project implements a FastMCP server that exposes Betfair Exchange market information as tools for use by a Large Language Model (LLM). It leverages the `betfairlightweight` Python library to interact with the Betfair API-NG.
## Features
* Retrieves Betfair account funds.
* Lists available event types (sports).
* Lists events within specific event types.
* Retrieves market catalogues for events.
* Fetches live market book data (prices, traded volume) for specific markets.
## Setup
### Prerequisites
* Python 3.8+
* `uv` (recommended for dependency management)
### 1. Install `uv` (if not already installed)
```bash
pipx install uv
# or
pip install uv
```
### 2. Create and Activate Virtual Environment
Navigate to the project directory (`~/code/betfair-api-mcp/`):
```bash
cd ~/code/betfair-api-mcp/
uv venv mcp_betfair_env
source mcp_betfair_env/bin/activate
```
### 3. Install Dependencies
```bash
uv pip install fastmcp betfairlightweight
```
## Configuration
The server requires your Betfair API credentials to function. It's highly recommended to set these as environment variables for security.
### Environment Variables
Set the following environment variables in your terminal session **before** running the server:
* `BETFAIR_USERNAME`: Your Betfair username.
* `BETFAIR_PASSWORD`: Your Betfair password.
* `BETFAIR_APP_KEY`: Your Betfair Application Key.
* `BETFAIR_CERTS_PATH`: (Optional) The absolute path to the directory containing your Betfair SSL certificates (`.crt` and `.key` files, or a single `.pem` file). Only required if you use certificate-based login.
**Example (Linux/macOS):**
```bash
export BETFAIR_USERNAME="your_betfair_username"
export BETFAIR_PASSWORD="your_betfair_password"
export BETFAIR_APP_KEY="your_betfair_app_key"
export BETFAIR_CERTS_PATH="/Users/youruser/betfair_certs/" # Example path
```
**Example (Windows Command Prompt):**
```cmd
set BETFAIR_USERNAME="your_betfair_username"
set BETFAIR_PASSWORD="your_betfair_password"
set BETFAIR_APP_KEY="your_betfair_app_key"
set BETFAIR_CERTS_PATH="C:\Users\youruser\betfair_certs\"
```
## Running the Server
There are two ways to run the MCP server:
**1. Standalone (for testing):**
* Ensure you are in the project directory (`~/code/betfair-api-mcp/`).
* Ensure your virtual environment is activated (`source mcp_betfair_env/bin/activate`).
* Ensure your Betfair API credentials are set as environment variables.
```bash
python main.py
```
The server will start and print "Starting Betfair Exchange MCP server..." and "Successfully logged into Betfair API." (or an error message if login fails).
**2. Via Gemini CLI:**
You can configure the Gemini CLI to run the server as a command. This is the recommended way to use the server with the CLI.
Add the following to your Gemini settings (`~/.gemini/settings.json` or `.gemini/settings.json` in your project root):
```json
{
"mcpServers": {
"betfair": {
"command": ["python", "main.py"],
"workingDirectory": "/betfair-api-mcp"
}
}
}
```
**Important:**
* Replace `betfair-api-mcp` with the absolute path to your project directory.
* Ensure that the `python` command in the `command` array points to the python executable within your virtual environment if it's not on your system's `PATH`. You can use the full path to the python executable (e.g., `betfair-api-mcp/mcp_betfair_env/bin/python`).
* The CLI will automatically manage starting and stopping the server process.
* You still need to set the Betfair environment variables in your shell session where you run the Gemini CLI.
## MCP Tools Exposed
The following tools are exposed by the FastMCP server for use by an LLM:
* `get_account_funds()`: Retrieves the current available funds in the Betfair account.
* `list_event_types(locale: Optional[str] = None)`: Retrieves a list of Event Types (i.e., Sports) available on the Betfair Exchange.
* `list_events(event_type_ids: List[str], locale: Optional[str] = None)`: Retrieves a list of Events for specified Event Types.
* `list_market_catalogue(event_ids: List[str], market_type_codes: Optional[List[str]] = None, max_results: int = 10, locale: Optional[str] = None)`: Retrieves information about published markets for specified events.
* `list_market_book(market_ids: List[str], include_traded_volume: bool = False, include_best_offers: bool = True, ladder_levels: int = 3, locale: Optional[str] = None)`: Retrieves dynamic data about markets, including prices, market status, and selection status.
