AI导哈

印度股票分析服务器

一个专为印度股票市场（NSE/BSE）设计的MCP服务器，提供投资组合推荐和市场洞察，集成MongoDB和Alpha Vantage API。

  • by ingpoc
  • Python
  • 本地部署
  • 8 星标
  • 更新于
在 GitHub 查看 ingpoc/stock_mcp_server

使用说明

印度股票分析MCP服务器

一个模型上下文协议（MCP）服务器，用于与MongoDB股票数据交互，以提供投资组合建议和市场见解，专门针对印度股市（NSE/BSE）。

概述

此MCP服务器集成了：

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

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

特性

  • 独家印度市场焦点：专为NSE和BSE上市股票设计
  • 直接访问MongoDB：在不经过API层的情况下直接查询MongoDB
  • 知识图谱集成：维护印度股票的持续分析数据
  • 阿尔法优势率限制：处理带有自动速率限制的自由层API限制
  • 模块化架构：干净、可维护的代码结构，关注点分离
  • 环境配置：使用.env便于配置
  • LLM优化数据：自动限制和简化数据响应，以便克劳德轻松处理
  • 分段投资组合分析：在较小的细分市场中处理大型投资组合，以防止超时

安装

先决条件

  • Python 3.9+
  • MongoDB在本地主机27017上运行，数据库为“stock_data”
  • Alpha Vantage API密钥（支持免费层，在https://www.alphavantage.co/support/#api-按键）
  • 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 Desktop使用配置文件连接到MCP服务器。您需要创建或编辑此文件以包含您的股票分析服务器。

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

    • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
    • 窗户： %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 必须使用连字符，而不是下划线
  • 这 MCP_SERVER_NAME env中的必须与服务器密钥匹配
  • 确保所有路径都是绝对路径

  1. 启动或重新启动Claude Desktop

  2. 验证服务器连接：

    • 打开克劳德桌面
    • 工具图标（锤子）应出现在界面中
    • 开始新的对话（重要-新工具可能不会出现在现有对话中）
    • 试着问一下你的股票投资组合

示例提示

配置后，您可以询问Claude：

  • “你能提供我的投资组合摘要吗？”
  • “分析我投资组合的第1部分”
  • “使用segment_size=8分析我投资组合的下一部分”
  • “用详细的指标分析我投资组合的第3部分”
  • “我投资组合第2部分的股票是什么？”
  • “在我的投资组合中，哪些行业最具代表性？”
  • “你能为我的印度股票投资组合提供建议吗？”
  • “分析我投资组合中的银行股”
  • “本季度我应该了解印度市场的哪些市场趋势？”
  • “我应该考虑出售我投资组合中的哪些股票？”
  • “哪些新的NSE股票可以补充我目前的投资组合？”
  • “为我找到本周BSE表现最佳的股票”
  • “你能找到信实工业股票的信息吗？”
  • “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. 开始新的对话 在克劳德做出改变后

  4. 启用开发人员模式 在克劳德的设置中

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

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

  7. 检查Claude应用程序日志:

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

常见问题

  1. 未找到Python：确保配置中的Python路径正确
  2. MongoDB连接问题：检查MongoDB是否在配置的URI上运行
  3. 工具架构问题：确保所有工具都有正确的模式定义
  4. 克劳德桌面版：将Claude Desktop更新到最新版本
  5. 服务器名称不匹配：代码中的服务器名称必须与配置文件匹配
  6. 大数据响应：如果Claude在处理大型数据集时遇到困难，请使用分段分析：
    • 首先，通过以下方式获取投资组合摘要 get_portfolio_summary
    • 然后一次分析一个片段 portfolio_analysis 使用分段参数
    • 使用较小的细分规模（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. 财务数据压缩:

    • 自动压缩财务数据响应
    • 将历史数据限制在最近两个时期
    • 删除元数据和内部字段
    • 将基本指标优先于综合数据

  3. 参数限制:

    • 投资组合分析：最多15只股票，每部分5只（详细分析3只）
    • 股票推荐：最多8个推荐
    • 移除分析：最多分析10个待移除的库存
    • 市场趋势：最多8只趋势股

  4. 智能细分:

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

  5. 响应大小管理:

    • 处理过程中响应大小的实时监控
    • 当响应超过大小阈值时自动简化
    • 当响应太大时，紧急回退到最小数据
    • 详细记录响应大小以进行故障排除

  6. 智能内部处理:

    • 分析功能在内部使用完整数据，同时呈现简化的结果
    • 市场趋势建议过滤掉投资组合中已有的股票
    • 财务数据压缩在减小大小的同时保留了关键指标

这些优化确保克劳德能够高效地处理您的股票数据，而不会被过多的信息淹没或超时。

测试

该存储库包括一个全面的测试套件，用于验证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测试

如果您想跳过对AlphaVantage进行实际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. 阿尔法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：要获得的建议类型（例如，“增长”、“价值”、“股息”）（默认值：“增长”）
      • limit：要返回的最大建议数（默认值：5，最大值：8）
    • 笔记：
      • 通过文本字段截断优化了Claude的响应
      • 建议被过滤，以排除已在投资组合中的股票
      • 响应大小受到监控，并在必要时进行简化

  • 获取删除建议：确定应从投资组合中删除的印度股票

    • 参数：
      • limit：要分析的最大股票数（默认值：5，最大值：10）
    • 笔记：
      • 自动分析移除候选人的投资组合持有情况
      • 识别利润下降、看跌趋势或基本面得分低的股票
      • 响应大小受到监控，并在必要时进行简化

市场趋势

  • 获取市场趋势建议：根据当前市场趋势，寻找必须购买的印度股票
    • 参数：
      • limit：要返回的最大建议数（默认值：5，最大值：8）
    • 笔记：
      • 自动排除您投资组合中已有的股票
      • 关注势头强劲、技术指标积极的股票
      • 响应大小受到监控，并在必要时进行简化

知识图谱

  • 查询知识图谱：查询印度股票知识图以获取历史分析和见解

市场数据

  • 获取Alpha Vantage数据：访问Alpha Vantage API印度股市数据，并享受免费分级限制
  • 搜索股票代码：按名称或关键字搜索印度股票代码

技术分析

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

    • 参数：
      • symbol：要分析的股票代码（例如“NSE:RELIANCE”）
    • 笔记：
      • 此工具需要对AlphaVantage进行多次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使用：

  1. 自动数据限制:

    • 查询结果的默认限制，以防止过多的信息淹没Claude
    • 默认情况下，投资组合持有量限制为10只股票（最多可配置50只）
    • 默认情况下，建议仅限5只股票
    • 投资组合分析最多限制为15只股票，每部分5只股票

  2. 数据简化:

    • 投资组合持股仅简化为基本字段（符号、数量、平均价格）
    • 需要分析时可以提供完整的详细信息，但隐藏在直接显示之外
    • 财务数据自动压缩，以关注基本指标
    • 截断文本字段以防止淹没Claude

  3. 参数控制:

    • 工具公开参数，允许Claude根据需要请求更多或更少的数据
    • 能够在摘要视图和详细视图之间切换
    • 控制分段大小和要分析的分段

  4. 分段处理:

    • 投资组合分析可以分段进行，以防止出现大规模响应
    • 每个分段处理一个子集的股票（默认值：每个分段5只股票）
    • 允许Claude分析大型投资组合，而不会出现连接超时
    • 基于分析类型的分段大小自动调整

  5. 响应大小管理:

    • 处理过程中响应大小的实时监控
    • 当响应超过大小阈值时自动简化
    • 当响应太大时，紧急回退到最小数据
    • 详细记录响应大小以进行故障排除

  6. 智能内部处理:

    • 分析功能在内部使用完整数据，同时呈现简化的结果
    • 市场趋势建议过滤掉投资组合中已有的股票
    • 财务数据压缩在减小大小的同时保留了关键指标

这些优化确保克劳德能够高效地处理您的股票数据，而不会被过多的信息淹没或超时。

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：控股集合名称（默认：控股）
  • MONGODB_FINANCIALS_COLLECTION：财务收款名称（默认：detailed_Financials）
  • MONGODB_KNOWLEDGE_GRAPH_COLLECTION：知识图集合名称（默认：stock_Knowledge_graph）

阿尔法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：服务器名称（默认：股票分析mcp）
  • MCP_SERVER_VERSION：服务器版本（默认值：0.1.0）

日志记录配置

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

缓存设置

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

许可证

MIT许可证

AlphaVantage 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限制，这也能提供价值

相关 MCP