What is Stock Mcp Service

The stock-mcp-service is a China stock market data service based on the MCP (Model Context Protocol), providing real-time stock prices, historical data, market indices, and technical analysis features.

Use cases

Use cases include real-time stock monitoring, historical data analysis for investment strategies, technical analysis for traders, and generating comprehensive stock reports for decision-making.

How to use

To use the stock-mcp-service, clone the project from GitHub, install the required dependencies using uv, and run the service with the command ‘uv run python stock_mcp_server.py’.

Key features

Key features include real-time stock data retrieval, historical K-line data, market index access, stock search functionality, technical indicators analysis (MA, MACD, RSI, KDJ, Bollinger Bands), comprehensive analysis reports, and built-in data caching.

Where to use

The stock-mcp-service can be used in financial applications, trading platforms, stock analysis tools, and any software requiring real-time or historical stock market data.

中国股票市场行情 MCP 服务

这是一个基于 MCP (Model Context Protocol) 的中国股票市场行情服务，提供实时股票价格、历史数据、市场指数、技术分析等全面功能。

🚀 功能特性

📊 基础数据

• 🔄 实时行情: 获取A股实时价格、涨跌幅、成交量等数据
• 📈 历史数据: 查询股票历史K线数据（日线、周线、月线）
• 📊 市场指数: 获取上证指数、深证成指、创业板指、科创50、沪深300、中证500等主要指数
• 🔍 股票搜索: 根据股票名称或代码搜索相关股票
• ⏰ 时间服务: 获取当前时间、交易状态、交易日判断等时间相关信息

📅 智能交易日历

• 🗓️ 真实交易日历: 使用akshare获取中国股市真实交易日历
• 🎯 节假日识别: 自动识别春节、国庆等法定节假日和调休安排
• 📊 交易日计算: 基于实际交易日数量计算历史数据范围
• 🔄 智能回退: 当交易日历不可用时，自动回退到简化判断逻辑
• ⚡ 缓存优化: 交易日历数据本地缓存，提高查询效率

📈 技术分析

• 📊 移动平均线: MA5、MA10、MA20、MA60
• 📈 MACD指标: DIF、DEA、MACD柱状图
• 📉 RSI指标: 相对强弱指数
• 🎯 KDJ指标: 随机指标K、D、J值
• 📊 布林带: 上轨、中轨、下轨
• 🎨 技术状态: 自动分析多头/空头排列、金叉死叉、超买超卖等

🔧 增强功能

• 📋 综合分析: 一键获取完整的股票分析报告
• ⚡ 数据缓存: 内置缓存机制，提高数据获取效率
• 🛡️ 错误处理: 完善的异常处理和NaN值处理
• 🎨 智能分析: 自动判断技术指标状态和趋势
• 📊 综合评价: 基于多个指标的综合信号分析
• 🔄 混合数据源: 智能切换数据源，确保数据完整性

🛡️ 安全与限制

• 🚦 请求频率限制: 每分钟最多100次请求，防止过度使用
• 📏 数据量限制: 历史数据最大365天，技术指标最大120天
• 🔒 输入验证: 严格验证股票代码格式和参数范围
• 🛡️ 错误信息清理: 自动清理敏感信息，避免内部细节泄露
• ⚡ 智能缓存: 5分钟数据缓存，减少重复请求

📦 安装依赖

# 安装uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装项目依赖
uv sync --no-install-project

🔧 使用方法

MCP客户端配置

在您的MCP客户端配置文件中添加以下配置：

{
  "mcpServers": {
    "stock-market": {
      "command": "uv",
      "args": [
        "--directory",
        "PATH_TO_YOUR_STOCK_MCP_SERVICE/stock_mcp_service",
        "run",
        "stock_mcp_server.py"
      ],
      "transportType": "stdio"
    }
  }
}

注意: 请将路径 PATH_TO_YOUR_STOCK_MCP_SERVICE/stock_mcp_service 替换为您的实际项目路径。

手动启动服务器（调试用）

# 使用uv运行
uv run python stock_mcp_server.py

🛠️ 可用工具

1. 获取当前时间

{
  "name": "get_current_time",
  "arguments": {
    "timezone": "Asia/Shanghai"
  }
}

2. 获取股票实时行情

{
  "name": "get_stock_realtime",
  "arguments": {
    "symbol": "600519"
  }
}

3. 获取股票历史数据（支持交易日计算）

{
  "name": "get_stock_history",
  "arguments": {
    "symbol": "600519",
    "period": "daily",
    "days": 30
  }
}

或使用具体日期：

{
  "name": "get_stock_history",
  "arguments": {
    "symbol": "600519",
    "period": "daily",
    "start_date": "20240101",
    "end_date": "20240131"
  }
}

4. 获取市场指数

{
  "name": "get_market_index",
  "arguments": {
    "random_string": "dummy"
  }
}

5. 搜索股票

{
  "name": "search_stock",
  "arguments": {
    "keyword": "茅台"
  }
}

6. 获取技术指标（限制最大120天）

{
  "name": "get_technical_indicators",
  "arguments": {
    "symbol": "600519",
    "period": "daily",
    "days": 30
  }
}

7. 获取综合分析

{
  "name": "get_comprehensive_analysis",
  "arguments": {
    "symbol": "600519"
  }
}

📊 技术指标说明

移动平均线 (MA)

• MA5: 5日移动平均线
• MA10: 10日移动平均线
• MA20: 20日移动平均线
• MA60: 60日移动平均线

MACD指标

• DIF: 快线，12日EMA - 26日EMA
• DEA: 慢线，DIF的9日EMA
• MACD: 柱状图，(DIF - DEA) × 2

RSI指标

• 相对强弱指数，范围0-100

• 80: 超买区域

• <20: 超卖区域

KDJ指标

• K值: 快速随机指标
• D值: 慢速随机指标
• J值: 3K - 2D

布林带

• 上轨: 中轨 + 2倍标准差
• 中轨: 20日移动平均线
• 下轨: 中轨 - 2倍标准差

⏰ 时间服务功能

智能交易日历

• 真实交易日历: 使用akshare的tool_trade_date_hist_sina()获取官方交易日历
• 节假日处理: 自动处理春节、国庆、清明、端午、中秋等法定节假日
• 调休识别: 识别因节假日调休导致的工作日非交易日情况
• 缓存机制: 交易日历按年缓存，每日自动更新

时间信息

• 当前时间: 北京时间（Asia/Shanghai时区）
• 时间戳: Unix时间戳
• 交易日判断: 基于真实交易日历判断是否为交易日
• 交易时间判断: 自动判断是否在交易时间内
  • 上午：9:30-11:30
  • 下午：13:00-15:00
• 下一个交易日: 自动计算下一个交易日期

智能日期范围

• 基于交易日的范围计算: get_date_range_for_trading_days()方法
• 自然日范围计算: get_date_range_for_days()方法
• 智能回退: 当交易日历不可用时，自动使用自然日计算
• 防止无限循环: 内置最大查找天数限制

🎯 技术状态分析

系统会自动分析以下技术状态：

• MA趋势: 多头排列/空头排列/震荡整理
• MACD: 金叉向上/死叉向下/震荡调整
• RSI: 超买区域/超卖区域/强势区域/弱势区域
• KDJ: 超买区域/超卖区域/金叉向上/死叉向下
• 布林带: 突破上轨/跌破下轨/中轨上方/中轨下方
• 综合评价: 偏多信号/偏空信号/信号中性

🔄 数据源优化

混合数据源策略

为确保数据完整性，系统采用智能数据源切换：

• 实时行情: 优先使用stock_zh_a_spot_em()
• 历史数据: 使用stock_zh_a_hist()
• 市场指数: 混合使用现货数据和历史数据接口
• 交易日历: 使用tool_trade_date_hist_sina()

数据处理优化

• NaN值处理: 自动处理pandas中的NaN值，转换为合适的默认值
• 类型转换: 安全的数据类型转换，避免转换错误
• 数据验证: 验证数据完整性和有效性

🛡️ 安全注意事项

部署安全

⚠️ 重要: 在生产环境部署此MCP服务时，请注意以下安全事项：

网络安全

• 🔒 不要直接暴露到公网: 此服务设计为本地或内网使用
• 🛡️ 使用防火墙: 如需网络访问，请配置适当的防火墙规则
• 🔐 VPN访问: 建议通过VPN或专用网络访问
• 📡 代理服务: 如需公网访问，请使用反向代理并配置SSL

访问控制

• 👥 用户认证: 在生产环境中实施用户认证机制
• 🎫 访问令牌: 考虑使用API密钥或访问令牌
• 📊 审计日志: 记录所有API调用和用户活动
• ⏱️ 会话管理: 实施适当的会话超时机制

资源保护

• 🚦 请求限制: 已内置每分钟100次请求限制
• 💾 内存监控: 监控服务内存使用情况
• 📈 性能监控: 监控API响应时间和错误率
• 🔄 自动重启: 配置服务异常时的自动重启机制

数据安全

• 🔒 敏感信息: 错误消息已自动清理敏感信息
• 📝 日志安全: 确保日志文件不包含敏感数据
• 🗄️ 数据存储: 缓存数据仅存储在内存中，不持久化
• 🔐 传输加密: 在网络传输中使用HTTPS

监控建议

• 📊 实时监控: 监控服务状态和性能指标
• 🚨 异常告警: 配置异常情况的告警机制
• 📈 使用统计: 跟踪API使用情况和趋势
• 🔍 安全扫描: 定期进行安全漏洞扫描

使用限制

• 📏 历史数据: 最大365天限制
• 🔧 技术指标: 最大120天限制
• 🚦 请求频率: 每分钟最多100次请求
• 💾 缓存时间: 数据缓存5分钟自动过期

🔧 参数说明

历史数据参数

• symbol: 6位数字股票代码（必需）
• period: 数据周期，支持 “daily”、“weekly”、“monthly”
• days: 获取天数，基于交易日计算，优先级高于start_date
• start_date: 开始日期，格式YYYYMMDD
• end_date: 结束日期，格式YYYYMMDD

技术指标参数

• symbol: 6位数字股票代码（必需）
• period: 数据周期，支持 “daily”、“weekly”、“monthly”
• days: 获取天数，默认30天，最大120天

搜索参数

• keyword: 搜索关键词，支持股票名称或代码片段
• 返回最多20条匹配结果

📝 更新日志

v2.0.0 - 安全与功能增强版

• ✅ 集成akshare真实交易日历
• ✅ 添加基于交易日的日期范围计算
• ✅ 实施请求频率限制（每分钟100次）
• ✅ 添加数据量上限保护（历史365天，技术指标120天）
• ✅ 优化错误消息，清理敏感信息
• ✅ 增强输入验证和参数限制
• ✅ 改进缓存机制和数据处理
• ✅ 添加安全部署指南

v1.0.0 - 基础功能版

• ✅ 实时股票行情查询
• ✅ 历史数据获取
• ✅ 市场指数监控
• ✅ 股票搜索功能
• ✅ 技术指标计算
• ✅ 综合分析报告

📄 许可证

MIT License

🤝 贡献

欢迎提交Issue和Pull Request来改进这个项目。

⚠️ 免责声明

本服务提供的股票数据仅供参考，不构成投资建议。投资有风险，入市需谨慎。使用者应当根据自己的判断做出投资决策，并承担相应的投资风险。