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 调用，提高响应时间。