Stock MCP

🚀 Stock MCP Server

An intelligent stock data service based on the Model Context Protocol, offering real-time data for A-shares, Hong Kong stocks, and US stocks, along with AI-driven in-depth analysis.

Quick Start • Features • API Documentation • Configuration Guide

✨ Features

• 🌐 Global Market Coverage - Access data for A-shares, Hong Kong stocks, and US stocks with a single click.
• 🤖 AI-Powered Analysis - Conduct news sentiment analysis, generate in-depth research reports, and perform intelligent searches.
• 🚀 Ready to Use - Deploy with Docker in one click and start the service within 5 minutes.
• 📊 Multi-Data Source Integration - Intelligently aggregate data from AKShare, Tushare, yFinance, and Finnhub.
• 💾 High-Performance Caching - Accelerate with Redis and enable automatic degradation for stability.

🚀 Quick Start

# 1. Clone the project
git clone <your-repo-url> && cd stock-mcp

# 2. Configure environment variables (Required: TUSHARE_TOKEN)
cp .env.example .env && vim .env

# 3. Start the service with one click
docker-compose up -d

# 4. Access the service
open http://localhost:9998/docs

🎯 Experience core features in 5 minutes:

# Query historical prices and AI analysis of Kweichow Moutai
curl "http://localhost:9998/stock/price?symbol=600519&start_date=2024-01-01&end_date=2025-01-01"

# Get real-time quotes of Apple
curl "http://localhost:9998/api/stock/news?symbol=AAPL"

# Query fundamental data of stocks
curl "http://localhost:9998/api/stock/fundamental?symbol=000008&curr_date=2025-06-01"

# Query multiple stocks in batches
curl -X POST "http://localhost:9998/api/stock/quotes" \
  -H "Content-Type: application/json" \
  -d '{"symbols": ["AAPL", "TSLA", "MSFT"]}'

🎯 Core Features

📋 API Interface Overview

💡 Tip: All interfaces support the three major markets of A-shares, Hong Kong stocks, and US stocks.
📚 Detailed Documentation: Access http://localhost:9998/docs after starting the service.

📊 Data Query Capabilities

• ✅ Real-time Quotes - Minute-level prices/volumes
• ✅ Historical Data - K-line charts, adjusted prices
• ✅ Financial Statements - Balance sheets, cash flows
• ✅ Technical Indicators - MACD, RSI, Bollinger Bands
• ✅ Fund Flow - Main funds, northbound funds

🤖 AI Enhancement

• 🔍 Intelligent Search - Tavily semantic search
• 📰 Sentiment Analysis - Multi-source news aggregation + scoring
• 📈 In-depth Research - AI-generated research reports
• 💡 Decision Support - Data-driven investment advice
• 🌐 Multi-language Support - Automatic recognition of Chinese and English

⚙️ Configuration Instructions

Core Configuration (.env file)

# 【Required】Access to A-share data (Apply at: https://tushare.pro/)
TUSHARE_TOKEN=your_token_here

# 【Optional】Proxy configuration (Recommended for accessing US stock data)
HTTP_PROXY=http://127.0.0.1:7890
HTTPS_PROXY=http://127.0.0.1:7890

# 【Optional】Enhanced features
TAVILY_API_KEY=your_key     # AI search and research
FINNHUB_API_KEY=your_key    # Enhanced news data
NEWS_API_KEY=your_key       # News aggregation

📡 API Interface Documentation

🎨 Interactive Documentation

Access the following addresses after starting the service to view the full Swagger UI documentation:

• Swagger UI: http://localhost:9998/docs
• ReDoc: http://localhost:9998/redoc

📊 Stock Data Interfaces

{
  "status": "success",
  "message": "Successfully obtained stock price data and analysis report",
  "data": "# AAPL Stock Analysis Report\n\n## 📊 Basic Information\n- **Stock Name**: Apple Inc.\n- **Stock Symbol**: AAPL\n- **Analysis Period**: July 12, 2025 - August 12, 2025\n\n## 💰 Price Performance\n- **Current Price**: $227.18\n- **Price Change During the Period**: $+18.80 (+9.02%)\n- **Highest Price During the Period**: $230.74\n- **Lowest Price During the Period**: $201.27\n- **Average Volume**: 60,489,490\n\n## 📈 Technical Indicators\n- **5-Day Moving Average**: $218.35\n- **20-Day Moving Average**: $212.25\n- **Recent Trend**: Upward"
}

curl -X GET "http://localhost:9998/stock/price?symbol=AAPL&start_date=2024-07-13&end_date=2025-07-13" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

curl -X GET "http://localhost:9998/api/stock/fundamental?symbol=000008&curr_date=2025-06-01" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

{
  "status": "success",
  "message": "Successfully obtained real-time quotes of AAPL",
  "data": {
    "ticker": "AAPL",
    "currentPrice": "256.48",
    "dailyChangePercent": "-0.0818107444777616",
    "peRatio": "38.919575",
    "marketCap": "3806263246848",
    "source": "yfinance"
  }
}

curl -X GET "http://localhost:9998/api/stock/news?symbol=AAPL" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

curl -X POST "http://localhost:9998/api/stock/quotes" \
  -H "Content-Type: application/json" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903" \
  -d '{"symbols": ["AAPL", "TSLA", "MSFT"]}'

📰 News Data Interfaces

curl -X GET "http://localhost:9998/api/stock/news?symbol=000001" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

curl -X GET "http://localhost:9998/api/stock/news/date?symbol=000001&target_date=2025-09-10&days_before=7" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

📅 Trading Calendar Interfaces

curl -X GET "http://localhost:9998/api/calendar/trading-days?symbol=000001&start_date=2025-01-01&end_date=2025-09-01" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

curl -X GET "http://localhost:9998/api/calendar/is-trading-day?symbol=000001&check_date=2025-09-30" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

curl -X GET "http://localhost:9998/api/calendar/trading-hours?symbol=000001&check_date=2025-09-30" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

{
  "status": "success",
  "message": "Successfully obtained the list of supported exchanges",
  "data": {
    "total_count": 200,
    "regions": {
      "USA": ["NYSE", "NASDAQ"],
      "China": ["XSHG", "XSHE"],
      "Europe": ["XPAR", "XLON"],
      "Asia-Pacific": ["NSE", "TSE"],
      "Canada": ["TSX"]
    },
    "all_exchanges": ["NYSE", "NASDAQ", "XSHG", "XSHE", "..."]
  }
}

curl -X GET "http://localhost:9998/api/calendar/supported-exchanges" \
  -H "Authorization: a7f3518b-2983-4d29-bd1d-15a13e470903"

🔐 Authentication Instructions

All API interfaces support optional Authorization Header for authentication:

-H "Authorization: your-api-token-here"

Get Token: Contact the administrator or set a custom token in the configuration file.

📊 Quick Testing

Use the following commands to quickly test the main interfaces:

# Query the stock price of Kweichow Moutai
curl "http://localhost:9998/stock/price?symbol=600519&start_date=2024-01-01&end_date=2025-01-01"

# Get real-time quotes of Apple
curl "http://localhost:9998/api/stock/news?symbol=AAPL"

# Check if today is a trading day
curl "http://localhost:9998/api/calendar/is-trading-day?symbol=000001&check_date=$(date +%Y-%m-%d)"

# Get all supported exchanges
curl "http://localhost:9998/api/calendar/supported-exchanges"

📖 API Design Principles

The APIs in this project follow the following design principles:

✅ RESTful Style - Use standard HTTP methods (GET/POST).
✅ Unified Response Format - All interfaces return a unified JSON structure.
✅ Detailed Error Information - Error responses include clear error codes and descriptions.
✅ OpenAPI 3.0 - Complete API specification documentation (View).
✅ Automatic Documentation Generation - Support for both Swagger UI and ReDoc.

🐳 Docker Deployment

Service Architecture

Common Commands

# Start the service
docker-compose up -d

# View logs
docker-compose logs -f stock-mcp

# Stop the service
docker-compose down

# Restart the service
docker-compose restart

# Rebuild
docker-compose up -d --build

🛠️ Troubleshooting

# Check the configuration
cat .env | grep REDIS_HOST
# Ensure that in the Docker environment: REDIS_HOST=redis

# Check the Redis status
docker-compose ps redis

# Check the proxy configuration
cat .env | grep PROXY
# In the Docker environment, use: HTTP_PROXY=http://host.docker.internal:7890

grep TUSHARE_TOKEN .env

More issues: Full Troubleshooting Guide

📚 Documentation

• 📡 Full API Documentation - Detailed descriptions, parameters, and examples for all interfaces.
• 💡 API Usage Examples - Code examples for real-world scenarios.
• 📖 User Guide - Configuration, deployment, and best practices.
• 🔧 Development Documentation - Architecture design and secondary development.
• 🌐 OpenAPI Specification - Standard API specification file.
• 💻 Swagger UI - Interactive API testing (access after starting the service).

🤝 Contribute

Welcome to submit Issues and Pull Requests!

# 1. Fork the project
# 2. Create a feature branch
git checkout -b feature/amazing-feature

# 3. Commit your code
git commit -m "Add: amazing feature"

# 4. Push and create a PR
git push origin feature/amazing-feature

📄 License

MIT License - See LICENSE

🙏 Acknowledgments

This project is built on the following excellent open-source projects:

MCP • FastAPI • AKShare • Tushare • yFinance • Tavily

⭐️ If this project is helpful to you, please give it a Star ⭐️