finance-mcp-alpha

v1.0.1

Published

2 months ago

MCP Server for calculating WorldQuant 101 Alpha factors using Tushare data

0High
0Medium
0Low

xingyuchen

mcp finance alpha worldquant tushare quantitative trading stock

📊 FinanceMCP-Alpha

A powerful Model Context Protocol (MCP) server for calculating WorldQuant 101 Alpha factors using real-time Chinese stock market data from Tushare. Built with TypeScript and designed for quantitative trading analysis and research.

✨ Features

🎯 7 Alpha Factors: Alpha3, Alpha13, Alpha15, Alpha16, Alpha44, Alpha50, Alpha55
📈 Real-time Data: Integrates with Tushare API for A-share market data
🔒 Secure: Token-based authentication via HTTP headers
🚀 Streamable HTTP: Modern MCP protocol support
📊 Comprehensive Analysis: Detailed factor statistics and trading signals
🎨 Beautiful Reports: Markdown-formatted analysis with visual indicators

🏗️ Architecture

src/
├── index.ts              # MCP server entry point
├── tools/
│   └── calculate_alpha.ts # Alpha calculation tool
├── alphas/
│   └── index.ts          # Alpha factor implementations
└── utils/
    ├── tushare.ts        # Tushare API client
    └── operators.ts      # Mathematical operators

📦 Installation

Option 1: Use as npm package

npm install finance-mcp-alpha

Option 2: Clone and build locally

git clone https://github.com/guangxiangdebizi/FinanceMCP-Alpha.git
cd FinanceMCP-Alpha
npm install
npm run build

🚀 Quick Start

1. Start the Server

npm start

The server will start on http://localhost:3000 by default.

🚀 FinanceMCP-Alpha Server Started
=====================================
Transport: Streamable HTTP
MCP Endpoint: http://localhost:3000/mcp
Health Check: http://localhost:3000/health
=====================================

2. Configure MCP Client

Add to your MCP client configuration (e.g., mcp.json or Claude Desktop config):

{
  "mcpServers": {
    "finance-alpha": {
      "type": "streamableHttp",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "X-Tushare-Token": "YOUR_TUSHARE_TOKEN_HERE"
      },
      "timeout": 600
    }
  }
}

⚠️ Important: Get your free Tushare token at https://tushare.pro/register

3. Use the Tool

Once connected, you can use the calculate_alpha tool:

Calculate Alpha factors for stock 000001.SZ from 20240101 to 20241011 
with factors Alpha3, Alpha13, Alpha50

📖 Alpha Factors

This package implements the following WorldQuant 101 Alpha factors:

Alpha#3

Formula: (-1 * correlation(rank(open), rank(volume), 10))
Use Case: Measures negative correlation between opening price ranks and volume ranks. High values suggest contrarian price-volume behavior.

Alpha#13

Formula: (-1 * rank(covariance(rank(close), rank(volume), 5)))
Use Case: Captures ranked covariance between closing prices and volume. Identifies price-volume anomalies.

Alpha#15

Formula: (-1 * sum(rank(correlation(rank(high), rank(volume), 3)), 3))
Use Case: Sum of ranked correlations between high prices and volume. Detects short-term momentum shifts.

Alpha#16

Formula: (-1 * rank(covariance(rank(high), rank(volume), 5)))
Use Case: Similar to Alpha13 but focuses on intraday volatility patterns using high prices.

Alpha#44

Formula: (-1 * correlation(high, rank(volume), 5))
Use Case: Negative correlation between high prices and volume ranks. Identifies volume divergence from price peaks.

Alpha#50

Formula: (-1 * ts_max(rank(correlation(rank(volume), rank(vwap), 5)), 5))
Use Case: Maximum ranked correlation between volume and VWAP. Measures volume-price efficiency.

Alpha#55

Formula: (-1 * correlation(rank((close - ts_min(low, 12)) / (ts_max(high, 12) - ts_min(low, 12))), rank(volume), 6))
Use Case: Correlation between normalized price position and volume. Captures momentum-volume relationships.

🔧 Tool Parameters

`calculate_alpha`

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | stock_code | string | ✅ | Stock code in Tushare format (e.g., 000001.SZ, 600000.SH) | | start_date | string | ✅ | Start date in YYYYMMDD format (e.g., 20240101) | | end_date | string | ✅ | End date in YYYYMMDD format (e.g., 20241011) | | factors | array | ✅ | List of factors: ["Alpha3", "Alpha13", "Alpha15", "Alpha16", "Alpha44", "Alpha50", "Alpha55"] |

Stock Code Format

Shenzhen Stock Exchange: XXXXXX.SZ (e.g., 000001.SZ - Ping An Bank)
Shanghai Stock Exchange: XXXXXX.SH (e.g., 600000.SH - SPD Bank)

📊 Output Format

The tool returns a comprehensive Markdown report including:

📈 Factor Summary Table: Current values, percentiles, and signals
🔍 Detailed Analysis: Statistical metrics for each factor
💡 Trading Signals: Buy/Sell/Hold recommendations based on percentile analysis
🎯 Overall Recommendation: Aggregated signal from all factors

Signal Interpretation

| Percentile | Signal | Emoji | Action | |------------|--------|-------|--------| | ≥ 80% | STRONG BUY | 🟢 | Strong buying opportunity | | 60-80% | BUY | 🟢 | Moderate buying opportunity | | 40-60% | HOLD | 🟡 | Neutral, wait for clearer signal | | 20-40% | SELL | 🔴 | Moderate selling pressure | | < 20% | STRONG SELL | 🔴 | Strong selling pressure |

🔐 Security Notes

Never commit your Tushare token to version control
Store tokens securely in your MCP client configuration
Use environment variables for server configuration
Token is passed via HTTP header, not stored in server

🛠️ Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

# Start production server
npm start

📝 Environment Variables

Create a .env file (optional):

PORT=3000

🧪 Testing

Test the health endpoint:

curl http://localhost:3000/health

Expected response:

{
  "status": "healthy",
  "transport": "streamable-http",
  "activeSessions": 0,
  "serverInfo": {
    "name": "FinanceMCP-Alpha",
    "version": "1.0.0"
  }
}

📚 Use Cases

Quantitative Trading: Integrate alpha factors into your trading strategies
Research: Analyze factor effectiveness across different stocks and time periods
Portfolio Management: Use factor signals for position sizing and rebalancing
Market Analysis: Understand price-volume relationships and market microstructure
AI-Assisted Trading: Leverage LLMs with real-time factor calculations

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

⚠️ Disclaimer

This software is for educational and research purposes only. Alpha factors are statistical indicators and should not be the sole basis for investment decisions. Past performance does not guarantee future results. Always conduct thorough research and consult with financial professionals before making investment decisions.

👤 Author

Xingyu Chen

🌐 GitHub: @guangxiangdebizi
💼 LinkedIn: Xingyu Chen
📦 npm: @xingyuchen
📧 Email: [email protected]

🙏 Acknowledgments

WorldQuant: For the Alpha101 factor formulas
Tushare: For providing comprehensive Chinese stock market data
Model Context Protocol: For the amazing MCP framework

📖 References

⭐ If you find this project helpful, please consider giving it a star on GitHub!

Happy Trading! 📈