finance-mcp-alpha

📊 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: [e-mail]

🙏 Acknowledgments

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

📖 References

• WorldQuant 101 Formulaic Alphas
• Tushare Pro API Documentation
• Model Context Protocol Specification

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

Happy Trading! 📈