Content
# Empyrical MCP Knowledge Base
This project is a comprehensive knowledge base for quantitative financial metrics, providing definitions, calculation methods, code implementations, and practical applications of quantitative financial metrics, along with implementations that offer these metrics as MCP (Model Context Protocol) services.
## Project Composition
This project is divided into two main parts:
1. **Financial Metrics Knowledge Base**: Detailed documentation of financial metrics, including definitions, calculation methods, code implementations, and application scenarios.
2. **Empyrical MCP Service**: An MCP service implementation based on the [Empyrical library](https://github.com/quantopian/empyrical), allowing financial metric calculations through API calls.
## Financial Metrics Documentation
### Return Metrics
- [Annual Return](docs/annual_return.md)
### Risk Metrics
- [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)
### Metrics Applicability Table
| Metric Name | Strategy Evaluation | Risk Management | Asset Allocation | Benchmark Comparison | Suitable for Long-Term | Suitable for Short-Term |
|-------------------|---------------------|------------------|------------------|----------------------|------------------------|-------------------------|
| Annual 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 MCP service implementation based on the Empyrical library, enabling AI to directly invoke financial metric calculation functionalities.
### Service Features
- High-performance MCP service implemented with FastAPI
- Supports calculations for all major financial metrics from the Empyrical library
- Provides a RESTful API interface
- Easy to integrate into AI assistants and applications
### Installation Guide
#### 1. Prerequisites
Ensure the following software is installed on your system:
- Python 3.8 or higher
- pip package manager
#### 2. Get the Code
```bash
# Clone the repository
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 (make sure to grant execute permissions 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
python3 -m uvicorn mcp_server.empyrical_mcp_server:app --reload
# Production environment startup method
python3 -m uvicorn mcp_server.empyrical_mcp_server:app --host 0.0.0.0 --port 8000
```
### Configure MCP Service in Cursor
#### Method 1: Edit mcp.json Configuration (Recommended)
Cursor uses the `mcp.json` file to manage MCP services. 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 Supported)
1. Open Cursor IDE
2. Click on "Settings" (or press Ctrl+,)
3. Search for "MCP" or navigate to the "MCP Service" 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 to the empyrical-mcp-knowledge-base directory
### Verify the Service is Running Properly
```bash
# Health check
curl http://127.0.0.1:8000/
# Get the list of available metrics
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/
# Test Sharpe Ratio calculation
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
- Ensure the service is started in the **project root directory** (empyrical-mcp-knowledge-base), not in the mcp_server subdirectory.
- Use the module import method to start (`python3 -m uvicorn`), rather than executing the script directly.
- If you encounter connection issues, check if the port is occupied, and consider changing the port number.
### Available Methods
The service provides various financial metric calculation methods. For a complete list and parameter descriptions, please refer to the [MCP Service 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
```
## Common Issues Troubleshooting
1. **Module Import Error**: If you encounter `ModuleNotFoundError: No module named 'mcp_server'`, ensure you are running the command in the project root directory.
2. **Connection Refused**: If you see `ConnectionRefusedError: [Errno 61] Connection refused`, ensure 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 metric calculation library.
## Feature Overview
This service enables AI assistants (such as Claude) to calculate various financial and portfolio analysis metrics, including:
- Annual Return
- Sharpe Ratio
- Sortino Ratio
- Maximum Drawdown
- Alpha/Beta
- Information Ratio
- Calmar Ratio
- Annual 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 with 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 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
Once the service is running, restart Cursor, and you can use the following functions in Claude's dialogue:
- `mcp_empyrical_annual_return` - Calculate annual 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.
