Kai Stock Market MCP

🚀 股票市場MCP服務器

這是一個全面的模型上下文協議（MCP）服務器，藉助yfinance提供印度和全球股票市場數據。它具備智能符號解析、即時數據以及高級圖表生成等功能，可同時服務於印度國家證券交易所（NSE）、孟買證券交易所（BSE）和國際市場。

🚀 快速開始

安裝與設置

前提條件

• Python 3.11 或更高版本
• 配置環境變量

快速啟動步驟

1. 克隆倉庫並進入項目目錄。
2. 創建環境配置文件：

cp .env.example .env

3. 配置 .env 文件：

AUTH_TOKEN=your_secure_auth_token_here
MY_NUMBER=your_validation_number_here

4. 安裝依賴項：

pip install -r requirements.txt

5. 啟動服務器：

python stock_market_server.py

服務器將在 http://0.0.0.0:8087 上可用。

Docker 快速啟動

# 本地構建並運行
docker build -t stock-market-mcp .
docker run -p 8087:8087 \
  -e AUTH_TOKEN=your-token \
  -e MY_NUMBER=91xxxxxxxxxx \
  stock-market-mcp

使用 Railway 部署

此應用針對 Railway 託管進行了優化，具備以下特性：

• 基於 Dockerfile 的部署
• 動態端口綁定
• 健康檢查端點
• 最小化 Docker 鏡像 詳細部署說明請參閱 RAILWAY_DEPLOY.md。

使用 Docker Compose 進行本地開發

# 複製環境變量
cp .env.example .env
# 使用你自己的值編輯 .env 文件

# 啟動服務
docker-compose up --build

✨ 主要特性

智能符號解析

• 智能名稱到符號轉換：可使用公司名稱，如 “Reliance”、“Apple”、“TCS”，而非精確的股票代碼。
• 模糊匹配：通過置信度評分處理拼寫錯誤和部分名稱。
• 上下文感知：為區域用戶優先顯示印度股票（.NS/.BO）。
• 多格式支持：同時接受精確的股票代碼（RELIANCE.NS）和自然名稱（Reliance）。

即時股票數據

• 即時報價：提供當前價格、漲跌情況、成交量和市值。
• 歷史數據：具備可配置時間範圍（1 天至 10 年以上）的價格歷史數據。
• 公司概況：包含詳細的基本面、財務指標和業務信息。
• 多股票支持：支持批量處理，便於進行投資組合分析。
• 快速報價：可快速查看價格，無需完整的公司詳情。

高級圖表生成

• 專業圖表：使用 matplotlib 生成高質量的金融風格可視化圖表。
• 多種圖表類型：包括價格圖表、燭臺圖、成交量分析和對比圖表。
• 技術指標：涵蓋移動平均線（MA20、MA50）、成交量加權平均價格（VWAP）和成交量趨勢。
• 對比分析：可對多隻股票的表現進行可視化對比。
• 可導出格式：生成的 PNG 格式圖表適用於報告和演示。

全面的財務分析

• 財務報表：提供損益表、資產負債表和現金流量分析。
• 盈利情報：包含歷史盈利數據、即將公佈的日期和分析師預測。
• 分析師覆蓋：提供買入/賣出/持有建議和目標價格。
• 所有權分析：分析機構持股、共同基金和主要股東情況。
• 市場研究：提供收入預測和盈利預測。

印度市場優化

• 聚焦 NSE/BSE：為印度證券交易所提供專門支持。
• 貨幣格式：使用盧比（₹）符號和印度數字格式（千萬/十萬）。
• NIFTY 50 集成：預加載熱門股票觀察列表，便於市場動態跟蹤和篩選。
• 主要指數：即時跟蹤 NIFTY 50、SENSEX、BANK NIFTY 和行業指數。
• 熱門股票：預配置 100 多家印度公司，可快速訪問。

📦 安裝指南

開發環境設置

# 克隆並安裝開發依賴項
git clone <repository-url>
cd stock-market-mcp
pip install -e ".[dev]"

💻 使用示例

智能符號解析

# 獲取即時報價
get_stock_quote("Reliance")  # 或 get_stock_quote("RELIANCE.NS")
# 獲取歷史數據
get_stock_history("TCS", "1y")  # 或 get_stock_history("Tata Consultancy", "1y")
# 獲取公司信息
get_stock_info("Apple")  # 或 get_stock_info("AAPL")
# 獲取多隻股票報價
get_multiple_stock_quotes("Reliance,TCS,Infosys")  # 或使用精確符號

市場分析

# 跟蹤指數
get_market_indices()
# 查看市場動態
get_market_movers("gainers")
# 比較股票
compare_stocks("RELIANCE.NS,TCS.NS")  # 或 compare_stocks("Reliance,TCS")
# 獲取分析師研究
get_analyst_recommendations("HDFC Bank")
# 獲取目標價格
get_analyst_price_targets("Apple")

圖表生成

# 生成價格圖表
create_stock_chart("Reliance", "6mo")  # 或 create_stock_chart("RELIANCE.NS", "6mo")
# 生成比較圖表
create_comparison_chart("TCS,Infosys", "1y")
# 生成燭臺圖
create_candlestick_chart("Apple", "3mo")
# 生成成交量分析圖表
create_volume_analysis_chart("HDFC Bank", "6mo")

財務分析

# 獲取盈利數據
get_earnings_data("Microsoft")
# 獲取財務報表
get_income_statement("TCS")
# 進行所有權分析
get_major_holders("Reliance")
# 獲取股息歷史
get_stock_dividends("HDFC Bank")

信息工具

# 獲取 MCP 功能指南
get_mcp_capabilities()
# 獲取快速幫助和常見使用示例
get_mcp_help()
# 獲取支持的股票列表
get_supported_stocks()
# 獲取作者信息
stock_mcp_authors_info()

📚 詳細文檔

可用工具

股票數據工具（12 個工具）

• get_stock_quote：通過智能符號解析獲取即時股票價格。
• get_multiple_stock_quotes：同時獲取多隻股票的批量報價。
• get_stock_info：獲取全面的公司信息和財務指標。
• get_stock_history：獲取多個時間範圍的歷史價格數據。
• get_stock_fast_info：快速查看價格，便於快速分析。
• get_stock_news：獲取最新的公司新聞和市場更新。
• get_stock_dividends：分析股息歷史和收益率。
• get_stock_splits：查看股票拆分和送股歷史。
• search_stocks：通過公司名稱查找股票，並提供搜索建議。
• resolve_symbol：智能將公司名稱轉換為股票代碼。
• get_income_statement：分析收入、利潤和費用。
• get_balance_sheet：分析資產、負債和權益。
• get_cashflow_statement：分析經營、投資和融資現金流。
• get_earnings_data：獲取季度和年度盈利歷史。
• get_earnings_dates：獲取即將公佈的盈利日曆和預測。

市場分析工具（8 個工具）

• get_market_indices：獲取主要的印度指數（NIFTY 50、SENSEX、BANK NIFTY）和全球市場指數。
• get_market_movers：查看 NIFTY 50 成分股中的漲幅和跌幅最大的股票。
• compare_stocks：對多隻股票的關鍵指標進行並排財務比較。
• get_analyst_recommendations：獲取分析師的買入/賣出/持有評級。
• get_analyst_price_targets：獲取共識價格預測和上漲潛力。
• get_major_holders：分析機構和共同基金的持股情況。
• get_earnings_estimates：獲取每股收益（EPS）預測和分析師共識。
• get_revenue_estimates：獲取收入預測和增長預期。

圖表生成工具（4 個工具）

• create_stock_chart：生成帶有移動平均線的專業價格圖表。
• create_comparison_chart：生成多隻股票表現比較圖表。
• create_candlestick_chart：生成詳細的 OHLC 燭臺圖，用於技術分析。
• create_volume_analysis_chart：使用 VWAP 指標進行高級成交量分析。

市場篩選工具（1 個工具）

• screen_stocks：根據條件（最活躍、漲幅最大、跌幅最大、市值等）篩選股票。

API 參考

股票數據工具

財務分析工具

市場分析工具

圖表生成工具

支持的時間範圍

• 日內：1d, 5d（每小時數據）
• 短期：1mo, 3mo, 6mo（每日數據）
• 中期：1y, 2y（每日數據）
• 長期：5y, 10y（每週數據）
• 特殊：ytd（年初至今）, max（所有可用數據）

符號格式與示例

• 印度股票：使用公司名稱，或為 NSE 股票添加 .NS，為 BSE 股票添加 .BO。
  • 示例："Reliance" → RELIANCE.NS, "TCS" → TCS.NS, "HDFC Bank" → HDFCBANK.NS
• 全球股票：使用公司名稱或標準股票代碼。
  • 示例："Apple" → AAPL, "Microsoft" → MSFT, "Google" → GOOGL
• 市場指數：使用雅虎財經的指數符號。
  • 印度：^NSEI（NIFTY 50）, ^BSESN（SENSEX）, ^NSEBANK（BANK NIFTY）
  • 全球：^GSPC（標準普爾 500）, ^DJI（道瓊斯指數）, ^IXIC（納斯達克指數）

智能解析示例

• 印度公司："Reliance Industries", "Tata Consultancy", "HDFC Bank", "Bharti Airtel"
• 全球公司："Apple Inc", "Microsoft Corporation", "Alphabet", "Amazon"
• 縮寫："TCS", "HUL", "L&T", "SBI", "ICICI"
• 部分名稱："Reliance", "Infosys", "HDFC"

🔧 技術細節

架構

• 面向服務的設計：採用模塊化架構，擁有專門的服務層。
• yfinance 集成：通過智能緩存從雅虎財經 API 獲取即時數據。
• FastMCP 框架：高性能的 MCP 服務器實現，支持異步操作。
• Pydantic 模型：在整個系統中實現類型安全的數據驗證和序列化。
• Bearer 認證：基於安全令牌的認證系統。

市場覆蓋範圍

• 印度市場：全面支持 NSE（.NS）和 BSE（.BO）上市證券。
• 全球市場：支持主要的國際交易所（納斯達克、紐約證券交易所、倫敦證券交易所等）。
• 市場指數：即時跟蹤 20 多個印度和全球指數。
• 符號範圍：預加載 1000 多種熱門股票，並具備智能名稱解析功能。

數據服務

• 即時報價：提供即時價格、成交量、市值和漲跌數據。
• 歷史分析：具備 10 多種時間範圍選項的全面歷史數據。
• 技術指標：包括移動平均線、VWAP、成交量分析和波動率指標。
• 財務指標：如市盈率、市淨率、每股收益、股息收益率、貝塔係數和增長率。
• 新聞集成：提供最新的公司新聞和影響市場的事件。

可視化與圖表

• 專業圖表：使用 matplotlib 生成針對金融數據優化的高質量圖表。
• 多種圖表類型：包括折線圖、燭臺圖、成交量分析和對比圖表。
• 技術分析：內置技術指標和趨勢分析。
• 導出格式：生成的 PNG 圖表適用於報告、演示和分析。

📄 許可證

文檔中未提及許可證相關信息。

項目結構

stock-market-mcp/
├── stock_market_server.py    # 主服務器入口點
├── auth.py                   # 認證提供程序
├── models.py                 # 數據模型和模式
├── services/                 # 業務邏輯層
│   ├── stock_service.py      # 股票數據操作
│   ├── market_data_service.py # 市場數據操作
│   └── chart_service.py      # 圖表生成
└── tools/                    # MCP 工具定義
    ├── stock_tools.py        # 股票相關工具
    ├── market_analysis_tools.py # 市場分析工具
    └── chart_tools.py        # 圖表生成工具

開發狀態

當前實現（v2.0+）

• 完整的 yfinance 集成：所有 25 個以上的股票數據工具均已完全實現，並具備錯誤處理功能。
• 智能符號解析：採用高級模糊匹配技術，預加載 100 多家公司。
• 高級圖表生成：使用 matplotlib 生成帶有技術指標的專業圖表。
• 全面的財務數據：提供即時報價、歷史數據、盈利信息和分析師覆蓋。
• 多市場支持：無縫集成印度（NSE/BSE）和全球市場。
• 可投入生產：具備強大的錯誤處理、數據驗證和性能優化。

近期更新（2024）

• 智能符號解析系統的全面實現。
• 新增 15 個以上的財務分析工具（盈利、建議、目標價格等）。
• 增強圖表生成功能，增加成交量分析和 VWAP 指標。
• 全面覆蓋印度市場，聚焦 NIFTY 50。
• 專業的圖表樣式和高級數據可視化。
• 強大的錯誤處理和優雅的回退機制。
• 智能緩存和性能優化。

工具覆蓋範圍

• 股票數據：12 個工具，涵蓋報價、歷史、新聞、股息、拆分等。
• 財務分析：8 個工具，用於盈利、報表和分析師覆蓋。
• 市場分析：8 個工具，用於指數、動態、比較和研究。
• 圖表生成：4 個工具，用於各種圖表類型和技術分析。
• 實用工具：5 個工具，用於搜索、解析、幫助、功能和作者信息。

貢獻說明

本項目採用現代 Python 開發實踐：

代碼質量與標準

• 格式化：使用 Black 代碼格式化工具，行限制為 120 個字符。
• 導入組織：使用 isort 確保一致的導入順序。
• 類型安全：使用 mypy 進行嚴格模式的類型檢查。
• 測試：使用 pytest 框架進行全面的測試覆蓋。
• 文檔：提供全面的文檔字符串和 API 文檔。

代碼架構

• 異步/等待：在整個系統中使用非阻塞操作，以實現高性能。
• 服務層：為股票數據、市場數據和圖表生成提供專門的服務。
• 模型驗證：使用 Pydantic 模型進行類型安全的數據驗證。
• 錯誤處理：具備全面的錯誤處理和優雅降級機制。
• 緩存：使用智能緩存減少 API 調用，提高響應時間。