Empyrical MCP知识库

March 29, 2025 · View on GitHub

该项目是一个全面的量化金融指标知识库，提供了量化金融指标的定义、计算方法、代码实现和实际应用介绍，同时包含了将这些指标作为MCP服务提供的实现。

项目组成

本项目分为两个主要部分：

金融指标知识库：详细的金融指标文档，包含定义、计算方法、代码实现和应用场景。
Empyrical MCP服务：基于Empyrical库的MCP服务实现，允许通过API调用进行金融指标计算。

金融指标文档

收益类指标

年化收益率 (Annual Return)

风险类指标

风险调整收益类指标

指标适用场景表

指标名称	策略评估	风险管理	资产配置	基准比较	适合长期	适合短期
年化收益率	✓		✓	✓	✓
最大回撤	✓	✓	✓		✓
波动率	✓	✓	✓		✓	✓
下行风险	✓	✓	✓		✓
跟踪误差			✓	✓	✓
风险价值		✓	✓			✓
夏普比率	✓		✓	✓	✓
索提诺比率	✓		✓	✓	✓
卡玛比率	✓		✓		✓
信息比率	✓		✓	✓	✓
阿尔法	✓		✓	✓	✓
贝塔	✓	✓	✓	✓	✓	✓

Empyrical MCP服务

本项目提供了基于Empyrical库的MCP服务实现，使AI能够直接调用金融指标计算功能。

服务特点

基于FastAPI实现的高性能MCP服务
支持所有Empyrical库的主要金融指标计算
提供RESTful API接口
易于集成到AI助手和应用程序中

安装指南

1. 前置条件

确保系统已安装以下软件：

Python 3.8或更高版本
pip包管理器

2. 获取代码

# 克隆仓库
git clone https://github.com/0xluluv587/empyrical-mcp-knowledge-base.git
cd empyrical-mcp-knowledge-base

3. 安装依赖

# 安装所有必要的依赖
python3 -m pip install -r mcp_server/requirements.txt

# 或使用安装脚本（需要先赋予执行权限）
chmod +x mcp_server/install.sh
./mcp_server/install.sh

启动服务

重要：必须在正确目录下启动服务，否则将出现模块导入错误。

# 在项目根目录下启动服务（开发模式，自动重载）
cd empyrical-mcp-knowledge-base  # 确保在项目根目录
python3 -m uvicorn mcp_server.empyrical_mcp_server:app --reload

# 生产环境启动方式
python3 -m uvicorn mcp_server.empyrical_mcp_server:app --host 0.0.0.0 --port 8000

在Cursor中配置MCP服务

方法一：编辑mcp.json配置（推荐方式）

Cursor使用mcp.json文件来管理MCP服务。按照以下步骤添加Empyrical服务：

找到并打开Cursor配置目录下的mcp.json文件：
- macOS: ~/.cursor/mcp.json 或 ~/Library/Application Support/Cursor/mcp.json
- Windows: %APPDATA%\Cursor\mcp.json
- Linux: ~/.config/Cursor/mcp.json
在mcpServers对象中添加Empyrical MCP服务配置：

{
  "mcpServers": {
    // 其他现有服务配置...
    
    "empyrical_mcp": {
      "isActive": true,
      "command": "python3",
      "args": [
        "-m",
        "uvicorn",
        "mcp_server.empyrical_mcp_server:app",
        "--host",
        "0.0.0.0",
        "--port",
        "8000"
      ],
      "cwd": "/YOUR_PATH/empyrical-mcp-knowledge-base"
    }
  }
}

将/YOUR_PATH/empyrical-mcp-knowledge-base替换为你的实际项目路径
- macOS/Linux示例: /Users/username/Coding/empyrical-mcp-knowledge-base
- Windows示例: C:\\Users\\username\\Coding\\empyrical-mcp-knowledge-base
保存文件并重启Cursor IDE

方法二：手动配置（如果GUI支持）

打开Cursor IDE
点击"设置"（或按下Ctrl+,）
搜索"MCP"或导航至"MCP服务"设置部分
点击"添加MCP服务"按钮
填写以下信息：
- 名称：empyrical_mcp
- 命令：python3
- 参数：-m uvicorn mcp_server.empyrical_mcp_server:app --host 0.0.0.0 --port 8000
- 工作目录：选择empyrical-mcp-knowledge-base目录的完整路径

验证服务是否正常运行

# 健康检查
curl http://127.0.0.1:8000/

# 获取可用的指标列表
curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "get_available_metrics", "params": {}, "id": 1}' http://127.0.0.1:8000/

# 测试夏普比率计算
curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "sharpe_ratio", "params": {"returns": [0.01, -0.02, 0.03, 0.01, -0.01, 0.02], "risk_free": 0.0}, "id": 1}' http://127.0.0.1:8000/

注意事项

确保在项目根目录（empyrical-mcp-knowledge-base）下启动服务，而不是在mcp_server子目录下
使用模块导入方式启动（python3 -m uvicorn），而不是直接执行脚本
如果遇到连接问题，检查端口是否已被占用，可尝试更改端口号

可用方法

服务提供多种金融指标计算方法，完整列表和参数说明请参阅MCP服务文档。

示例数据

项目提供了数据生成工具，用于生成测试和演示用的金融数据：

cd empyrical-mcp-knowledge-base
python3 -m mcp_server.example_data_generator

常见问题排查

模块导入错误：如果出现ModuleNotFoundError: No module named 'mcp_server'，请确保在项目根目录下运行命令。
连接被拒绝：如果出现ConnectionRefusedError: [Errno 61] Connection refused，请确保服务已成功启动，并检查IP和端口配置。

依赖安装问题：如果遇到依赖冲突，建议创建专用虚拟环境：

python3 -m venv .venv
source .venv/bin/activate  # Linux/Mac
# 或 .venv\Scripts\activate  # Windows
pip install -r mcp_server/requirements.txt

许可证

该项目采用MIT许可证。详细信息请参阅LICENSE文件。

Empyrical MCP 服务

这是一个基于Model Context Protocol（MCP）的服务，提供对Empyrical金融指标计算库的访问。

功能概述

此服务使AI助手（如Claude）能够计算各种金融和投资组合分析指标，包括：

年化收益率
夏普比率
索提诺比率
最大回撤
阿尔法/贝塔
信息比率
卡玛比率
年化波动率
下行风险
跟踪误差
风险价值(VaR)

快速开始

方法一：使用Docker（推荐）

# 克隆仓库
git clone https://github.com/0xluluv587/empyrical-mcp-knowledge-base.git
cd empyrical-mcp-knowledge-base

# 运行设置脚本
./run_mcp_server.sh

方法二：使用npx

# 直接通过npx运行（从本地目录）
npx /path/to/empyrical-mcp-knowledge-base

# 或者在仓库目录中运行
cd empyrical-mcp-knowledge-base
npm start

方法三：手动运行Python服务

# 安装依赖
pip install fastapi uvicorn pandas numpy empyrical

# 运行服务
cd empyrical-mcp-knowledge-base
python -m uvicorn mcp_server.empyrical_mcp_server:app --host 0.0.0.0 --port 8001

在Cursor中使用

服务启动后，重启Cursor，然后就可以在Claude对话中使用以下函数：

mcp_empyrical_annual_return - 计算年化收益率
mcp_empyrical_sharpe_ratio - 计算夏普比率
mcp_empyrical_max_drawdown - 计算最大回撤

示例提示：

请使用empyrical服务计算以下收益率数据的夏普比率:
[0.01, -0.02, 0.03, 0.01, -0.01, 0.02]
无风险收益率为0.001

API参考

服务提供JSON-RPC API，端点为 http://localhost:8001/。

示例请求：

{
  "jsonrpc": "2.0",
  "method": "sharpe_ratio",
  "params": {
    "returns": [0.01, -0.02, 0.03, 0.01, -0.01, 0.02],
    "risk_free": 0.001
  },
  "id": 1
}

故障排除

如果MCP服务无法正常工作：

确保服务正在运行 (curl http://localhost:8001/ 应返回服务信息)
检查Cursor日志 (~/Library/Logs/Claude/mcp.log 和 ~/Library/Logs/Claude/mcp-server-empyrical_mcp.log)
重新运行设置脚本并重启Cursor