印度股票分析 MCP 服务器

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

概述

此 MCP 服务器与以下内容集成：

1. MongoDB 数据库 (stock_data)，用于直接访问股票数据
2. Alpha Vantage API，用于印度市场数据（仅限 NSE/BSE），具有免费层级的限制
3. 知识图谱，用于持久的印度股票分析

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

特性

• 独家关注印度市场：专为 NSE 和 BSE 上市股票设计
• 直接 MongoDB 访问：直接查询 MongoDB，无需通过 API 层
• 知识图谱集成：维护印度股票的持久分析数据
• Alpha Vantage 速率限制：通过自动速率限制处理免费层级 API 限制
• 模块化架构：具有关注点分离的清晰、可维护的代码结构
• 环境配置：使用 .env 文件进行轻松配置
• LLM 优化数据：自动限制和简化数据响应，以便 Claude 轻松处理
• 分段投资组合分析：将大型投资组合分成较小的部分进行处理，以防止超时

安装

前提条件

• Python 3.9+
• MongoDB 在 localhost:27017 上运行，数据库为 "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 配置
   MONGODB_URI=mongodb://localhost:27017
   MONGODB_DB_NAME=stock_data
   
   # Alpha Vantage API
   ALPHA_VANTAGE_API_KEY=your_api_key_here
   
   # 印度股票市场设置
   ALPHA_VANTAGE_DEFAULT_EXCHANGE=NSE  # NSE 或 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 桌面应用程序版本：将 Claude 桌面应用程序保持更新到最新版本
5. 服务器名称不匹配：代码中的服务器名称必须与配置文件匹配
6. 大型数据响应：如果 Claude 难以处理大型数据集，请使用分段分析：
   • 首先使用 get_portfolio_summary 获取投资组合摘要
   • 然后使用 portfolio_analysis 和 segment 参数一次分析一个段
   • 对于详细分析，使用较小的段大小（3-5 只股票）

处理大型投资组合

对于大型投资组合（20+ 只股票），服务器实现了分段方法：

1. 获取投资组合摘要：

   • 使用 get_portfolio_summary 查看您的投资组合的概览
   • 这显示了总股票数、行业和推荐的分段

2. 分段分析：

   • 使用带有 segment 参数的 portfolio_analysis
   • 从第 1 段开始，然后逐步完成每个段
   • 示例："分析我的投资组合的第 1 段"，然后 "分析第 2 段..."

3. 控制段大小：

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

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 文件。最后，您将看到测试结果的摘要：

=== 测试结果摘要 ===
database_connection: ✅ 通过
portfolio_holdings: ✅ 通过
knowledge_graph: ✅ 通过
symbol_formatting: ✅ 通过
alpha_vantage_api: ✅ 通过
trending_stocks: ✅ 通过
tools_handler: ✅ 通过

总体：7/7 测试通过

故障排除测试

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

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           # 主要入口点
├── src/                # 源代码
│   ├── __init__.py     # 包初始化
│   ├── config.py       # 配置模块
│   ├── handlers/       # MCP 处理程序实现
│   │   ├── __init__.py
│   │   ├── resources.py  # 资源处理程序
│   │   ├── tools.py      # 印度股票分析的工具处理程序
│   │   └── prompts.py    # 提示处理程序
│   └── utils/          # 实用程序模块
│       ├── __init__.py
│       ├── database.py   # MongoDB 操作
│       └── alpha_vantage.py  # 印度市场的 Alpha Vantage API 操作
├── test_mcp_server.py  # 全面测试脚本
├── test_client.py      # 简单测试客户端
├── requirements.txt    # 依赖项
└── .env.example        # 示例环境配置

工具

服务器提供以下 MCP 工具，按类别组织：

投资组合分析

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

股票推荐

• 获取股票推荐：获取基于财务指标添加印度股票的建议

  • 参数：
    • criteria：要获取的推荐类型（例如，“增长”、“价值”、“股息”）（默认：“增长”）
    • 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 进行了优化，其中包括：

• 速率限制为每分钟 5 次 API 调用
• 每日限制为 500 次 API 调用
• 支持关键端点：
  • 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 限制，这也能提供价值