内容
# Betfair 接口 MCP 服务器
本项目实现了一个 FastMCP 服务器，暴露Betfair交易所的市场信息，作为大型语言模型（LLM）的工具。它利用 `betfairlightweight` Python库与Betfair API-NG交互。
## 功能
* 获取Betfair账户资金。
* 列出可用的事件类型（体育）。
* 列出特定事件类型下的事件。
* 获取事件的市场目录。
* 获取特定市场的实时市场书籍数据（价格、交易量）。
## 设置
### 先决条件
* Python 3.8+
* `uv`（推荐用于依赖管理）
### 1. 安装 `uv`（如果尚未安装）
```bash
pipx install uv
# 或
pip install uv
```
### 2. 创建并激活虚拟环境
导航到项目目录（`~/code/betfair-api-mcp/`）：
```bash
cd ~/code/betfair-api-mcp/
uv venv mcp_betfair_env
source mcp_betfair_env/bin/activate
```
### 3. 安装依赖
```bash
uv pip install fastmcp betfairlightweight
```
## 配置
服务器需要您的Betfair API凭证才能运行。强烈建议将这些凭证设置为环境变量以确保安全。
### 环境变量
在运行服务器之前，在终端会话中设置以下环境变量：
* `BETFAIR_USERNAME`：您的Betfair用户名。
* `BETFAIR_PASSWORD`：您的Betfair密码。
* `BETFAIR_APP_KEY`：您的Betfair应用程序密钥。
* `BETFAIR_CERTS_PATH`：（可选）包含您的Betfair SSL证书（`.crt`和`.key`文件，或单个`.pem`文件）的目录的绝对路径。仅在您使用基于证书的登录时需要。
**示例（Linux/macOS）：**
```bash
export BETFAIR_USERNAME="您的Betfair用户名"
export BETFAIR_PASSWORD="您的Betfair密码"
export BETFAIR_APP_KEY="您的Betfair应用程序密钥"
export BETFAIR_CERTS_PATH="/Users/youruser/betfair_certs/" # 示例路径
```
**示例（Windows 命令提示符）：**
```cmd
set BETFAIR_USERNAME="您的Betfair用户名"
set BETFAIR_PASSWORD="您的Betfair密码"
set BETFAIR_APP_KEY="您的Betfair应用程序密钥"
set BETFAIR_CERTS_PATH="C:\Users\youruser\betfair_certs\"
```
## 运行服务器
有两种方法可以运行MCP服务器：
**1. 独立运行（用于测试）：**
* 确保您位于项目目录（`~/code/betfair-api-mcp/`）。
* 确保您的虚拟环境已激活（`source mcp_betfair_env/bin/activate`）。
* 确保您的Betfair API凭证已设置为环境变量。
```bash
python main.py
```
服务器将启动并打印"Starting Betfair Exchange MCP server..."和"Successfully logged into Betfair API."（或登录失败时的错误消息）。
**2. 通过 Gemini CLI：**
您可以配置Gemini CLI以运行服务器作为命令。这是与CLI一起使用服务器的推荐方式。
在您的Gemini设置中添加以下内容（`~/.gemini/settings.json`或项目根目录下的`.gemini/settings.json`）：
```json
{
"mcpServers": {
"betfair": {
"command": ["python", "main.py"],
"workingDirectory": "/betfair-api-mcp"
}
}
}
```
**重要：**
* 将 `betfair-api-mcp` 替换为您的项目目录的绝对路径。
* 确保 `command` 数组中的 `python` 命令指向您的虚拟环境中的python可执行文件，如果它不在系统的 `PATH` 中。您可以使用python可执行文件的完整路径（例如 `betfair-api-mcp/mcp_betfair_env/bin/python`）。
* CLI将自动管理服务器进程的启动和停止。
* 您仍然需要在运行Gemini CLI的shell会话中设置Betfair环境变量。
## 暴露的MCP工具
FastMCP服务器为LLM暴露了以下工具：
* `get_account_funds()`：获取Betfair账户中当前可用的资金。
* `list_event_types(locale: Optional[str] = None)`：获取Betfair交易所上可用的事件类型（即体育）列表。
* `list_events(event_type_ids: List[str], locale: Optional[str] = None)`：获取指定事件类型的事件列表。
* `list_market_catalogue(event_ids: List[str], market_type_codes: Optional[List[str]] = None, max_results: int = 10, locale: Optional[str] = None)`：获取指定事件的已发布市场的相关信息。
* `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)`：获取市场的动态数据，包括价格、市场状态和选择状态。
