Indian Stock Analysis MCP Server

印度股票分析 MCP 服务

一个用于与 MongoDB 股票数据交互的模型上下文协议（MCP）服务，专为印度股市（NSE/BSE）提供投资组合建议和市场洞察。

概述

此 MCP 服务集成了：

1. 用于直接访问股票数据的 MongoDB 数据库（stock_data）
2. 用于获取印度市场数据（仅限 NSE/BSE）的 Alpha Vantage API，受免费套餐限制
3. 用于持久化印度股票分析的知识图谱

它支持 Claude 通过 Claude 桌面应用直接访问你的印度股票投资组合持仓、分析股票表现并提供个性化建议，同时构建持久化知识图谱，以提升上下文感知能力。

功能

• 专注印度市场：专为在 NSE 和 BSE 上市的股票设计
• 直接访问 MongoDB：直接查询 MongoDB，无需经过 API 层
• 知识图谱集成：为印度股票维护持久化分析数据
• Alpha Vantage 速率限制：通过自动限流处理免费套餐的 API 限制
• 模块化架构：代码结构清晰、易于维护，职责划分明确
• 环境配置：使用 .env 轻松配置
• 针对大模型优化的数据：自动限制并简化数据响应，方便 Claude 处理
• 分段分析投资组合：将大型投资组合拆分为较小部分进行处理，以避免超时

安装

先决条件

• Python 3.9+
• 在 localhost:27017 上运行的 MongoDB，数据库名称为 "stock_data"
• Alpha Vantage API 密钥（支持免费套餐，可在 https://www.alphavantage.co/support/#api-key 获取）
• Claude 桌面应用（可在 https://claude.ai/download 下载）

设置

1. 克隆此代码库：

   git clone <repository-url>
   cd stock-mcp-server
   

2. 安装依赖项：

   pip install -r requirements.txt
   

3. 根据示例创建 .env 文件：

   cp .env.example .env
   

4. 编辑 .env 文件以配置你的设置：

   # MongoDB Configuration
   MONGODB_URI=mongodb://localhost:27017
   MONGODB_DB_NAME=stock_data
   
   # Alpha Vantage API
   ALPHA_VANTAGE_API_KEY=your_api_key_here
   
   # Indian Stock Market Settings
   ALPHA_VANTAGE_DEFAULT_EXCHANGE=NSE  # NSE or BSE
   

使用方法

启动 MCP 服务

python server.py

配置 Claude 桌面应用

Claude 桌面应用使用配置文件连接到 MCP 服务。你需要创建或编辑此文件，将股票分析服务添加进去。

1. 在以下位置创建或编辑配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

2. 添加股票分析 MCP 服务配置：

{
  "mcpServers": {
    "stock-analysis-mcp": {
      "command": "/path/to/your/python",
      "args": [
        "/path/to/stock_mcp_server/server.py"
      ],
      "cwd": "/path/to/stock_mcp_server",
      "env": {
        "ALPHA_VANTAGE_API_KEY": "your_api_key_here",
        "MONGODB_URI": "mongodb://localhost:27017",
        "MONGODB_DB_NAME": "stock_data",
        "MONGODB_HOLDINGS_COLLECTION": "holdings",
        "MONGODB_FINANCIALS_COLLECTION": "detailed_financials",
        "MONGODB_KNOWLEDGE_GRAPH_COLLECTION": "stock_knowledge_graph",
        "ALPHA_VANTAGE_BASE_URL": "https://www.alphavantage.co/query",
        "ALPHA_VANTAGE_RATE_LIMIT_MINUTE": "5",
        "ALPHA_VANTAGE_RATE_LIMIT_DAY": "500",
        "ALPHA_VANTAGE_DEFAULT_EXCHANGE": "NSE",
        "MCP_SERVER_NAME": "stock-analysis-mcp",
        "MCP_SERVER_VERSION": "0.1.0",
        "LOG_LEVEL": "INFO",
        "CACHE_ENABLED": "True",
        "CACHE_TTL": "3600"
      }
    }
  }
}

重要提示：

• 使用 Python 可执行文件的完整路径（例如，/usr/bin/python3 或 C:\Python39\python.exe）
• 服务键 stock-analysis-mcp 必须使用连字符，不能使用下划线
• env 中的 MCP_SERVER_NAME 必须与服务键一致
• 确保所有路径均为绝对路径

3. 启动或重启 Claude 桌面应用

4. 验证服务连接：

   • 打开 Claude 桌面应用
   • 界面中应出现工具图标（锤子）
   • 开始新的对话（重要：新工具可能不会显示在现有对话中）
   • 尝试询问有关你股票投资组合的问题

提示词示例

配置完成后，你可以询问 Claude：

• “可以总结一下我的投资组合吗？”
• “分析我投资组合中的第 1 段”
• “使用 segment_size=8 分析我投资组合中的下一段”
• “使用详细指标分析我投资组合中的第 3 段”
• “我投资组合的第 2 段中有哪些股票？”
• “我的投资组合中哪些行业占比最高？”
• “可以为我的印度股票投资组合提供建议吗？”
• “分析我投资组合中的银行股”
• “本季度我应该关注印度市场的哪些趋势？”
• “我应该考虑卖出投资组合中的哪些股票？”
• “哪些新的 NSE 股票可以补充我当前的投资组合？”
• “帮我找出本周 BSE 上表现最好的股票”
• “可以查找 Reliance Industries 股票的相关信息吗？”
• “TCS 股票有哪些技术指标？”
• “搜索印度市场中与 HDFC 相关的股票”

故障排除

MCP 工具未显示

如果服务器成功启动，但工具没有显示在 Claude 中：

1. 检查日志：

   tail -f ~/Library/Logs/Claude/mcp-server-stock-analysis-mcp.log
   

2. 确认服务器名称：

   • 确保 claude_desktop_config.json 中的服务器键使用连字符（stock-analysis-mcp）
   • 确保 MCP_SERVER_NAME 环境变量与此名称一致

3. 在 Claude 中开始新的对话

4. 在 Claude 的设置中启用开发者模式

5. 检查路径：确保配置中的所有路径都是绝对路径且正确无误

6. Python 完整路径：使用 Python 可执行文件的完整路径（例如，运行 which python 查找路径）

7. 检查 Claude 应用日志：

   tail -f ~/Library/Logs/Claude/app.log
   

常见问题

1. 找不到 Python：确保配置中的 Python 路径正确
2. MongoDB 连接问题：检查 MongoDB 是否正在配置的 URI 上运行
3. 工具架构问题：确保所有工具都有正确的架构定义
4. Claude Desktop 版本：将 Claude Desktop 更新到最新版本
5. 服务器名称不匹配：代码中的服务器名称必须与配置文件中的名称一致
6. 数据响应过大：如果 Claude 难以处理大型数据集，请使用分段分析：
   • 首先使用 get_portfolio_summary 获取投资组合摘要
   • 然后使用 portfolio_analysis，通过 segment 参数一次分析一个部分
   • 使用较小的分段大小（3-5 只股票）进行详细分析

处理大型投资组合

对于大型投资组合（20 只及以上股票），服务器会采用分段处理方式：

1. 获取投资组合摘要：

   • 使用 get_portfolio_summary 查看投资组合概况
   • 其中会显示股票总数、行业和建议的分段方式

2. 分段分析：

   • 使用 portfolio_analysis 和 segment 参数
   • 从第 1 段开始，然后依次分析后续各段
   • 示例：“分析我的投资组合第 1 段”，然后“分析第 2 段……”

3. 控制分段大小：

   • 默认分段大小为 5 只股票
   • 使用 segment_size 参数调整（每段 1-5 只股票）
   • 示例：“使用 segment_size=3 分析第 1 段，以进行详细分析”

4. 选择详细程度：

   • 使用 include_details=false 快速查看概况（默认）
   • 使用 include_details=true 获取全面的指标和见解
   • 使用详细分析时，系统会自动减小分段大小，以避免超时

5. 管理响应大小：

   • 服务器会自动监控响应大小，并在需要时简化数据
   • 文本字段会被截断，以避免 Claude 接收的信息过多
   • 财务指标会经过精简，重点保留关键信息
   • 如果响应过大，系统会自动简化，并发出通知

性能优化

该服务包含多项优化，确保 Claude 能高效处理股票数据：

1. 自适应响应大小：

   • 在处理过程中自动监控响应大小
   • 响应超过大小阈值时动态简化
   • 将文本字段截断至最多 50-100 个字符
   • 移除非必要数据字段

2. 金融数据压缩：

   • 自动压缩金融数据响应
   • 历史数据最多保留最近 2 个周期
   • 移除元数据和内部字段
   • 优先呈现关键指标，而非完整数据

3. 参数限制：

   • 投资组合分析：最多 15 只股票，每个分段最多 5 只（详细分析时为 3 只）
   • 股票推荐：最多 8 条推荐
   • 移除分析：最多分析 10 只待移除股票
   • 市场趋势：最多 8 只热门股票

4. 智能分段：

   • 根据分析类型自动调整分段大小
   • 详细分析采用更小的分段，以防超时
   • 在分析过程中跟踪进度，以识别瓶颈

5. 响应大小管理：

   • 在处理过程中实时监控响应大小
   • 响应超过大小阈值时自动简化
   • 响应可能过大时，紧急回退至最少数据
   • 详细记录响应大小，便于排查问题

6. 智能内部处理：

   • 分析函数在内部使用完整数据，同时呈现简化结果
   • 市场趋势推荐会过滤掉投资组合中已有的股票
   • 金融数据压缩会保留关键指标，同时缩减数据大小

这些优化可确保 Claude 高效处理您的股票数据，避免被过多信息淹没或发生超时。

测试

此代码库包含一套全面的测试，用于验证 MCP 服务的功能。

可用测试

• test_mcp_server.py：用于验证 MCP 服务中所有端点和工具的综合测试脚本。
• test_client.py：用于测试 MCP 服务端点的简单客户端。
• test_server_startup.sh：用于测试服务启动流程的脚本

运行测试

快速启动测试

验证服务能否正常启动：

./test_server_startup.sh

综合测试脚本

运行综合测试脚本：

python test_mcp_server.py

此脚本将测试服务的各个方面，包括：

• MongoDB 连接
• 数据库操作（投资组合持仓、知识图谱）
• 印度股票代码格式化
• Alpha Vantage API 集成
• 热门股票功能
• MCP 工具处理程序

跳过 Alpha Vantage API 测试

如果您想跳过会实际调用 Alpha Vantage API 的测试（以避免触及速率限制）：

python test_mcp_server.py --skip-alpha-vantage

测试结果

脚本会将详细日志输出到控制台和 test_mcp_server.log 文件。结束时，您将看到测试结果摘要：

=== Test Results Summary ===
database_connection: ✅ PASSED
portfolio_holdings: ✅ PASSED
knowledge_graph: ✅ PASSED
symbol_formatting: ✅ PASSED
alpha_vantage_api: ✅ PASSED
trending_stocks: ✅ PASSED
tools_handler: ✅ PASSED

Overall: 7/7 tests passed

测试故障排除

如果测试失败，请检查以下内容：

1. 数据库连接：确保 MongoDB 正在配置的 URI（默认值：mongodb://localhost:27017）上运行，并且 stock_data 数据库存在。

2. Alpha Vantage API：检查您的 API 密钥是否已设置在 .env 文件中，以及是否已超出速率限制。

3. 数据可用性：某些测试需要 MongoDB 集合中已有数据（例如投资组合持仓）。确保数据库中包含所需数据。

4. 网络问题：Alpha Vantage 测试需要互联网连接。

退出代码

• 0：所有测试均已通过
• 1：一个或多个测试失败

这样，您就可以将测试集成到持续集成流水线中，并通过检查非零退出代码来判断测试结果。

印度股市笔记

在处理印度股市时，请注意：

• NSE 代码的格式为 NSE:SYMBOL（例如，NSE:RELIANCE）
• BSE 代码的格式为 BSE:CODE（例如，BSE:500325）
• 如果未指定交易所，则默认使用 NSE
• Alpha Vantage 免费套餐限制为每分钟 5 次调用、每天 500 次调用
• 此服务专为印度股票设计，不会处理其他市场的请求

架构

该项目采用模块化架构，以提高可维护性并实现关注点分离：

├── server.py           # Main entry point
├── src/                # Source code
│   ├── __init__.py     # Package initialization
│   ├── config.py       # Configuration module
│   ├── handlers/       # MCP handler implementations
│   │   ├── __init__.py
│   │   ├── resources.py  # Resource handlers
│   │   ├── tools.py      # Tool handlers for Indian stock analysis
│   │   └── prompts.py    # Prompt handlers
│   └── utils/          # Utility modules
│       ├── __init__.py
│       ├── database.py   # MongoDB operations
│       └── alpha_vantage.py  # Alpha Vantage API operations for Indian market
├── test_mcp_server.py  # Comprehensive test script
├── test_client.py      # Simple test client
├── requirements.txt    # Dependencies
└── .env.example        # Example environment configuration

工具

该服务提供以下 MCP 工具，按类别整理：

投资组合分析

• 获取投资组合持仓：获取当前印度股票投资组合及基本信息
  • 参数：
    • limit：返回的最大持仓数量（默认值：10，最大值：50）
    • summary：返回简化的股票数据（默认值：true）
• 获取投资组合摘要：获取投资组合的概览
  • 返回：
    • 股票总数
    • 行业分类
    • 分段指南
    • 分析建议
• 分析投资组合：使用指标和建议分析投资组合持仓
  • 参数：
    • limit：要分析的最多股票数量（默认值：10，最大值：15）
    • include_details：包含全面的指标（默认值：false）
    • segment：要分析的股票分段（默认值：1）
    • segment_size：每个分段的股票数量（默认值：5，最大值：5）
  • 注意：
    • 进行详细分析时，分段大小会自动缩减为 3
    • 系统会监控响应大小，并在必要时进行简化
    • 文本字段最多截断至 50 个字符

股票推荐

• 获取股票推荐：根据财务指标，获取可加入投资组合的印度股票推荐

  • 参数：
    • criteria：推荐类型（例如，“growth”“value”“dividend”）（默认值：“growth”）
    • limit：返回的最多推荐数量（默认值：5，最大值：8）
  • 注意：
    • 响应针对 Claude 进行了优化，并会截断文本字段
    • 推荐结果会排除投资组合中已有的股票
    • 系统会监控响应大小，并在必要时进行简化

• 获取移除建议：识别应从投资组合中移除的印度股票

  • 参数：
    • limit：要分析的最多股票数量（默认值：5，最大值：10）
  • 注意：
    • 自动分析投资组合持仓，找出适合移除的股票
    • 识别利润下滑、走势看跌或基本面评分较低的股票
    • 系统会监控响应大小，并在必要时进行简化

市场趋势

• 获取市场趋势推荐：根据当前市场趋势，寻找必买的印度股票
  • 参数：
    • limit：返回的最多推荐数量（默认值：5，最大值：8）
  • 注意：
    • 自动排除投资组合中已有的股票
    • 重点关注动能强劲且技术指标为正的股票
    • 系统会监控响应大小，并在必要时进行简化

知识图谱

• 查询知识图谱：查询印度股票知识图谱，进行历史分析并获取洞察

市场数据

• 获取 Alpha Vantage 数据：在免费套餐限制下，访问 Alpha Vantage API 提供的印度股市数据
• 搜索股票代码：按名称或关键词搜索印度股票代码

技术分析

• 获取技术分析：获取印度股票的技术分析指标（SMA、RSI）

  • 参数：
    • symbol：要分析的股票代码（例如，“NSE:RELIANCE”）
  • 注意：
    • 此工具需要多次调用 Alpha Vantage API
    • 如果短时间内连续发起多次分析请求，可能会触发速率限制

• 获取优化后的技术分析：智能技术分析，避免触发速率限制

  • 参数：
    • symbol：要分析的股票代码（例如，“NSE:RELIANCE”）
    • indicators：要分析的指标列表，以逗号分隔（例如，“SMA,RSI”）
  • 注意：
    • 执行预检，确保 API 调用可用
    • 仅针对请求的指标发起必要的 API 调用
    • 触发速率限制时提供教育内容
    • 更高效地使用每分钟 5 次调用的限额

API 管理

• 获取 Alpha Vantage API 状态：检查当前 API 调用状态和速率限制
  • 注意：
    • 显示当前分钟时段内剩余的可用 API 调用次数
    • 显示近期 API 调用历史记录
    • 提供何时发起调用的建议
    • 帮助 Claude 高效管理每分钟 5 次调用的限制

知识图谱

服务器在 MongoDB 中维护一个知识图谱（集合：stock_knowledge_graph），用于存储：

• 印度股票的历史分析
• 在 NSE 和 BSE 上市公司的绩效指标和趋势
• 投资组合纳入／排除建议
• 技术和基本面洞见
• 印度市场特有的趋势和模式

这能为 Claude 提供关于你的印度股票投资组合和关注股票的持久记忆。

面向 Claude 的数据优化

此服务器采用多种策略来优化供 Claude 使用的数据：

1. 自动限制数据：

   • 默认限制查询结果，避免过多信息让 Claude 应接不暇
   • 投资组合持仓默认限制为 10 只股票（可配置为最多 50 只）
   • 推荐默认限制为 5 只股票
   • 投资组合分析最多包含 15 只股票，每个分段包含 5 只股票

2. 简化数据：

   • 将投资组合持仓简化为仅包含必要字段（代码、数量、平均价格）
   • 需要分析时可获取完整详情，但不在直接显示中呈现
   • 自动压缩财务数据，重点保留关键指标
   • 截断文本字段，避免 Claude 应接不暇

3. 参数控制：

   • 工具提供参数，允许 Claude 按需请求更多或更少的数据
   • 可在摘要视图和详细视图之间切换
   • 可控制分段大小以及要分析的分段

4. 分段处理：

   • 可分段执行投资组合分析，避免响应过大
   • 每个分段处理一部分股票（默认：每段 5 只股票）
   • 允许 Claude 分析大型投资组合，避免连接超时
   • 根据分析类型自动调整分段大小

5. 响应大小管理：

   • 处理过程中实时监控响应大小
   • 响应超过大小阈值时自动简化
   • 响应过大时紧急回退到最少数据
   • 详细记录响应大小，便于排查问题

6. 智能内部处理：

   • 分析函数在内部使用完整数据，同时仅呈现简化结果
   • 市场趋势建议会排除已在投资组合中的股票
   • 压缩财务数据，在缩小数据量的同时保留关键指标

这些优化可确保 Claude 高效处理你的股票数据，避免被过多信息淹没或遭遇超时。

Alpha Vantage 免费层支持

此服务针对 Alpha Vantage 的免费层 API 进行了优化，其中包括：

• 每分钟最多调用 API 5 次
• 每天最多调用 API 500 次
• 支持以下关键端点：
  • GLOBAL_QUOTE - 当前价格信息
  • TIME_SERIES_DAILY - 每日价格历史
  • OVERVIEW - 公司信息
  • SYMBOL_SEARCH - 查找印度股票代码
  • 基本技术指标（SMA、RSI）

此服务会自动进行速率限制，确保调用次数不超过这些限制。

配置

此服务使用以下环境变量（在 .env 中定义）：

MongoDB 配置

• MONGODB_URI：MongoDB 连接字符串（默认值：mongodb://localhost:27017）
• MONGODB_DB_NAME：数据库名称（默认值：stock_data）
• MONGODB_HOLDINGS_COLLECTION：持仓集合名称（默认值：holdings）
• MONGODB_FINANCIALS_COLLECTION：财务数据集合名称（默认值：detailed_financials）
• MONGODB_KNOWLEDGE_GRAPH_COLLECTION：知识图谱集合名称（默认值：stock_knowledge_graph）

Alpha Vantage API

• ALPHA_VANTAGE_API_KEY：你的 Alpha Vantage API 密钥
• ALPHA_VANTAGE_BASE_URL：Alpha Vantage API URL（默认值：https://www.alphavantage.co/query）
• ALPHA_VANTAGE_RATE_LIMIT_MINUTE：每分钟允许调用 API 的次数（默认值：5）
• ALPHA_VANTAGE_RATE_LIMIT_DAY：每天允许调用 API 的次数（默认值：500）
• ALPHA_VANTAGE_DEFAULT_EXCHANGE：印度股票的默认交易所（默认值：NSE）

MCP 服务配置

• MCP_SERVER_NAME：服务名称（默认值：stock-analysis-mcp）
• MCP_SERVER_VERSION：服务版本（默认值：0.1.0）

日志配置

• LOG_LEVEL：日志级别（默认值：INFO）
• LOG_FORMAT：日志消息格式

缓存设置

• CACHE_ENABLED：启用缓存（默认值：True）
• CACHE_TTL：缓存生存时间（秒）（默认值：3600）

许可证

MIT 许可证

Alpha Vantage API 管理

此服务具备完善的 Alpha Vantage API 调用管理机制，确保不超过免费层限制：

速率限制跟踪

• 维护每分钟时间窗口内 API 调用次数的全局计数器
• 自动检测并处理 Alpha Vantage 返回的速率限制响应
• 通过 get_alpha_vantage_status 工具提供状态信息

智能调用管理

• 预检：发起 API 调用前，工具会检查调用是否会超出速率限制
• 成本感知处理：为每个 API 函数分配“成本”，以跟踪其影响
• 优雅降级：达到速率限制时，工具会提供静态数据或教育内容
• 定向调用：可将技术分析配置为仅获取特定指标

后备机制

• 受到速率限制时，系统会提供替代内容：
  • 热门股票的静态市场数据
  • 关于技术指标的教育内容
  • 可用时提供历史数据
  • 明确说明何时可以重试

使用示例

以下是 Claude 高效使用 API 的方式：

1. 先检查 API 状态：

   • “继续之前，我先检查 Alpha Vantage API 状态”
   • 这有助于规划如何在每分钟 5 次调用的限制内完成请求

2. 使用优化后的工具：

   • “我会使用优化后的技术分析，只获取 SMA 指标”
   • 这样只会为获取所需信息发起必要的 API 调用

3. 批量处理相似请求：

   • “我先收集所有股票代码，然后一起查询”
   • 这有助于避免重复或不必要的 API 调用

4. 适时使用静态数据：

   • “由于我们受到速率限制，我暂时使用静态趋势数据”
   • 即使达到 API 限制，也能提供有用信息