Content
# Empyrical MCP Knowledge Base
This project is a comprehensive knowledge base of quantitative financial indicators, providing definitions, calculation methods, code implementations, and practical applications of quantitative financial indicators, while also including implementations of these indicators as an MCP service.
## Project Composition
This project is divided into two main parts:
1. **Financial Metrics Knowledge Base**: A detailed documentation of financial metrics, including definitions, calculation methods, code implementations, and application scenarios.
2. **Empyrical MCP Service**: An implementation of the MCP service based on the [Empyrical library](https://github.com/quantopian/empyrical), allowing for financial metric calculations through API calls.
## Financial Metrics Documentation
### Revenue Metrics
- [年化收益率 (Annual Return)](docs/annual_return.md)
### Risk Indicators
- [Maximum Drawdown (最大回撤)](docs/max_drawdown.md)
- [Volatility (波动率)](docs/volatility.md)
- [Downside Risk (下行风险)](docs/downside_risk.md)
- [Tracking Error (跟踪误差)](docs/tracking_error.md)
- [Value at Risk (风险价值, VaR)](docs/value_at_risk.md)
### Risk-Adjusted Return Metrics
- [Sharpe Ratio](docs/sharpe_ratio.md)
- [Sortino Ratio](docs/sortino_ratio.md)
- [Calmar Ratio](docs/calmar_ratio.md)
- [Information Ratio](docs/information_ratio.md)
- [Alpha & Beta](docs/alpha_beta.md)
### Applicable Scenarios for Metrics
| Metric Name | Strategy Evaluation | Risk Management | Asset Allocation | Benchmark Comparison | Suitable for Long Term | Suitable for Short Term |
|-------------|---------------------|------------------|------------------|----------------------|-----------------------|------------------------|
| Annualized Return (年化收益率) | ✓ | | ✓ | ✓ | ✓ | |
| Maximum Drawdown (最大回撤) | ✓ | ✓ | ✓ | | ✓ | |
| Volatility (波动率) | ✓ | ✓ | ✓ | | ✓ | ✓ |
| Downside Risk (下行风险) | ✓ | ✓ | ✓ | | ✓ | |
| Tracking Error (跟踪误差) | | | ✓ | ✓ | ✓ | |
| Value at Risk (风险价值) | | ✓ | ✓ | | | ✓ |
| Sharpe Ratio (夏普比率) | ✓ | | ✓ | ✓ | ✓ | |
| Sortino Ratio (索提诺比率) | ✓ | | ✓ | ✓ | ✓ | |
| Calmar Ratio (卡玛比率) | ✓ | | ✓ | | ✓ | |
| Information Ratio (信息比率) | ✓ | | ✓ | ✓ | ✓ | |
| Alpha (阿尔法) | ✓ | | ✓ | ✓ | ✓ | |
| Beta (贝塔) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
## Empyrical MCP Service
This project provides an implementation of the MCP service based on the Empyrical library, enabling AI to directly invoke financial indicator calculation functions.
### Service Features
- High-performance MCP service implemented based on FastAPI
- Supports the calculation of major financial indicators from all Empyrical libraries
- Provides RESTful API interface
- Easy to integrate into AI assistants and applications
### Installation Guide
#### 1. Prerequisites
Make sure the system has the following software installed:
- Python 3.8 or higher
- pip package manager
#### 2. Get the Code
```bash
```
# Clone the Repository
```bash
git clone https://github.com/0xluluv587/empyrical-mcp-knowledge-base.git
cd empyrical-mcp-knowledge-base
```
#### 3. Install Dependencies
```bash
# Install all necessary dependencies
python3 -m pip install -r mcp_server/requirements.txt
# Or use the installation script (execute permission needs to be granted first)
chmod +x mcp_server/install.sh
./mcp_server/install.sh
```
### Start the Service
**Important**: The service must be started in the correct directory; otherwise, module import errors will occur.
```bash
# Start the service in the project root directory (development mode, auto-reload)
cd empyrical-mcp-knowledge-base # Ensure you are in the project root directory
python3 -m uvicorn mcp_server.empyrical_mcp_server:app --reload
# Production Environment Startup Method
```bash
python3 -m uvicorn mcp_server.empyrical_mcp_server:app --host 0.0.0.0 --port 8000
```
### Configuring MCP Service in Cursor
#### Method 1: Edit the mcp.json Configuration (Recommended)
Cursor uses the `mcp.json` file to manage the MCP service. Follow these steps to add the Empyrical service:
1. Locate and open the mcp.json file in the Cursor configuration directory:
- macOS: `~/.cursor/mcp.json` or `~/Library/Application Support/Cursor/mcp.json`
- Windows: `%APPDATA%\Cursor\mcp.json`
- Linux: `~/.config/Cursor/mcp.json`
2. Add the Empyrical MCP service configuration in the `mcpServers` object:
```json
{
"mcpServers": {
// Other existing service configurations...
"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"
}
}
}
```
3. Replace `/YOUR_PATH/empyrical-mcp-knowledge-base` with your actual project path
- macOS/Linux example: `/Users/username/Coding/empyrical-mcp-knowledge-base`
- Windows example: `C:\\Users\\username\\Coding\\empyrical-mcp-knowledge-base`
4. Save the file and restart the Cursor IDE.
#### Method 2: Manual Configuration (if GUI is supported)
1. Open Cursor IDE
2. Click on "Settings" (or press Ctrl+,)
3. Search for "MCP" or navigate to the "MCP Services" settings section
4. Click the "Add MCP Service" button
5. Fill in the following information:
- Name: empyrical_mcp
- Command: python3
- Arguments: -m uvicorn mcp_server.empyrical_mcp_server:app --host 0.0.0.0 --port 8000
- Working Directory: Select the full path of the empyrical-mcp-knowledge-base directory
### Verify if the service is running properly
```bash
```
# Health Check
curl http://127.0.0.1:8000/
# Get Available Metrics List
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/
# Testing Sharpe Ratio Calculation
```bash
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/
```
### Notes
- Make sure to start the service in the **project root directory** (empyrical-mcp-knowledge-base), not in the mcp_server subdirectory.
- Start using the module import method (`python3 -m uvicorn`), rather than executing the script directly.
- If you encounter connection issues, check if the port is already in use, and try changing the port number.
### Available Methods
The service provides various methods for calculating financial indicators. For a complete list and parameter descriptions, please refer to the [MCP Server Documentation](mcp_server/README.md).
## Example Data
The project provides a data generation tool for generating financial data for testing and demonstration purposes:
```bash
cd empyrical-mcp-knowledge-base
python3 -m mcp_server.example_data_generator
```
## Troubleshooting Common Issues
1. **Module Import Error**: If you encounter `ModuleNotFoundError: No module named 'mcp_server'`, please ensure that you are running the command from the project root directory.
2. **Connection Refused**: If you see `ConnectionRefusedError: [Errno 61] Connection refused`, please ensure that the service has started successfully and check the IP and port configuration.
3. **Dependency Installation Issues**: If you encounter dependency conflicts, it is recommended to create a dedicated virtual environment:
```bash
python3 -m venv .venv
source .venv/bin/activate # Linux/Mac
# or .venv\Scripts\activate # Windows
pip install -r mcp_server/requirements.txt
```
## License
This project is licensed under the MIT License. For more details, please refer to the [LICENSE](LICENSE) file.
# Empyrical MCP Service
This is a service based on the Model Context Protocol (MCP) that provides access to the [Empyrical](https://github.com/quantopian/empyrical) financial metrics calculation library.
## Feature Overview
This service enables AI assistants (such as Claude) to calculate various financial and portfolio analysis metrics, including:
- Annualized Return
- Sharpe Ratio
- Sortino Ratio
- Maximum Drawdown
- Alpha/Beta
- Information Ratio
- Calmar Ratio
- Annualized Volatility
- Downside Risk
- Tracking Error
- Value at Risk (VaR)
## Quick Start
### Method 1: Using Docker (Recommended)
```bash
# Clone the Repository
git clone https://github.com/0xluluv587/empyrical-mcp-knowledge-base.git
cd empyrical-mcp-knowledge-base
# Run the Setup Script
./run_mcp_server.sh
```
### Method 2: Using npx
```bash
# Run directly via npx (from local directory)
npx /path/to/empyrical-mcp-knowledge-base
# Or run in the repository directory
cd empyrical-mcp-knowledge-base
npm start
```
### Method 3: Manually Run the Python Service
```bash
# Install Dependencies
pip install fastapi uvicorn pandas numpy empyrical
# Run the Service
cd empyrical-mcp-knowledge-base
python -m uvicorn mcp_server.empyrical_mcp_server:app --host 0.0.0.0 --port 8001
```
## Using in Cursor
After the service starts, restart Cursor, and then you can use the following functions in the Claude conversation:
- `mcp_empyrical_annual_return` - Calculate annualized return
- `mcp_empyrical_sharpe_ratio` - Calculate Sharpe ratio
- `mcp_empyrical_max_drawdown` - Calculate maximum drawdown
Example prompt:
```
Please use the empyrical service to calculate the Sharpe ratio for the following return data:
[0.01, -0.02, 0.03, 0.01, -0.01, 0.02]
The risk-free rate is 0.001
```
## API Reference
The service provides a JSON-RPC API, with the endpoint at `http://localhost:8001/`.
Example request:
```json
{
"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
}
```
## Troubleshooting
If the MCP service is not functioning properly:
1. Ensure the service is running (`curl http://localhost:8001/` should return service information)
2. Check the Cursor logs (`~/Library/Logs/Claude/mcp.log` and `~/Library/Logs/Claude/mcp-server-empyrical_mcp.log`)
3. Rerun the setup script and restart Cursor
