股票_mcp_服务器

Name: 股票_mcp_服务器
Author: ingpoc

作者：ingpoc3 星标更新：2025-03-11

安装使用来源：spider==github.com

项目介绍

印度股市分析MCP服务器

这是一个用于与MongoDB股票数据交互以提供投资组合建议和市场洞察的Model Context Protocol (MCP)服务器，专门针对印度股市（NSE/BSE）。

概述

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

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

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

功能

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

安装

先决条件

Python 3.9+
在本地主机27017运行的MongoDB，数据库名为"stock_data"
Alpha Vantage API密钥（支持免费层级，获取地址：https://www.alphavantage.co/support/#api-key）
Claude桌面应用（下载地址：https://claude.ai/download）

设置

克隆此仓库：

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

安装依赖项：
```
pip install -r requirements.txt
```
从示例创建一个.env文件：
```
cp .env.example .env
```

编辑.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服务器。您需要创建或编辑此文件以包含您的股票分析服务器。

创建或编辑配置文件的位置：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
添加股票分析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必须与服务器键匹配
确保所有路径都是绝对路径

启动或重新启动Claude桌面应用
验证服务器连接：
- 打开Claude桌面应用
- 工具图标（锤子）应在界面中出现
- 开始一个新的对话（重要 - 新工具可能不会出现在现有对话中）
- 尝试询问关于您的股票投资组合的问题

示例提示

一旦配置完成，您可以向Claude提问：

"你能提供我的投资组合概要吗？"
"分析我的投资组合的第一部分"
"使用segment_size=8分析我的投资组合的下一个部分"
"使用详细指标分析我的投资组合的第三部分"
"我的投资组合第二部分有哪些股票？"
"哪些行业在我的投资组合中最占优势？"
"你能提供关于我的印度股票投资组合的建议吗？"
"分析我投资组合中的银行股"
"这个季度我在印度市场应该注意哪些市场趋势？"
"我应该考虑出售投资组合中的哪些股票？"
"哪些新的NSE股票可以补充我当前的投资组合？"
"找到本周在BSE上表现最好的股票"
"你能找到关于Reliance Industries股票的信息吗？"
"TCS股票的技术指标是什么？"
"搜索印度市场中的HDFC相关股票"

故障排除

MCP工具未显示

如果尽管服务器成功启动，但工具在Claude中仍未显示：

检查日志：

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

验证服务器命名：
- 确保claude_desktop_config.json中的服务器键使用连字符（stock-analysis-mcp）
- 确保环境变量中的MCP_SERVER_NAME与此名称匹配
在更改后开始新的对话
启用开发者模式：在Claude的设置中启用
检查路径：确保配置中的所有路径都是绝对且正确的
完整的Python路径：使用Python可执行文件的完整路径（例如，运行which python以找到它）
检查Claude应用日志：
```
tail -f ~/Library/Logs/Claude/app.log
```

常见问题

找不到Python：确保配置中的Python路径是正确的
MongoDB连接问题：检查MongoDB是否正在配置的URI上运行
工具模式问题：确保所有工具都有适当的模式定义
Claude桌面版本：保持Claude桌面更新到最新版本
服务器名称不匹配：代码中的服务器名称必须与配置文件匹配
大数据响应：如果Claude难以处理大量数据，请使用分段分析：
- 首先使用get_portfolio_summary获取投资组合概要
- 然后使用portfolio_analysis逐个分析每个部分
- 使用较小的分段大小（3-5只股票）进行详细分析

处理大型投资组合

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

获取投资组合概要：
- 使用get_portfolio_summary查看投资组合概览
- 显示总股票数、行业分布及推荐分段
按分段分析：
- 使用portfolio_analysis和segment参数
- 从第一部分开始，然后逐步分析每一部分
- 示例："分析我的投资组合的第一部分"，然后"分析我的投资组合的第二部分..."
控制分段大小：
- 默认分段大小为5只股票
- 使用segment_size参数调整（1-5只股票每段）
- 示例："使用segment_size=3进行详细分析，分析我的投资组合的第一部分"
请求详细程度：
- 使用include_details=false进行快速概览（默认）
- 使用include_details=true进行全面指标和见解
- 当使用详细分析时，分段大小会自动减少以防止超时
响应大小管理：
- 服务器自动监控响应大小并在必要时简化数据
- 文本字段被截断以防止压垮Claude
- 财务指标被压缩以聚焦于关键信息
- 如果响应过大，会自动简化并通知

性能优化

服务器包括多项优化措施，确保Claude能够高效处理股票数据：

自适应响应大小：
- 自动监控处理过程中的响应大小
- 当响应超过大小阈值时动态简化
- 截断文本字段至最大50-100字符
- 移除非关键数据字段
财务数据压缩：
- 自动压缩财务数据响应
- 限制历史数据至最近两个时期
- 移除元数据和内部字段
- 优先关键指标而非全面数据
参数限制：
- 投资组合分析：最多15只股票，每段5只（详细分析时3只）
- 股票推荐：最多8条推荐
- 移除分析：最多10只股票分析移除
- 市场趋势：最多8只热门股票
智能分段：
- 根据分析类型自动调整分段大小
- 详细分析时使用较小分段以防止超时
- 分析过程中跟踪进度以识别瓶颈
响应大小管理：
- 实时监控处理过程中的响应大小
- 当响应超过大小阈值时自动简化
- 当响应过大时自动回退到最小数据
- 详细记录响应大小以供故障排除
智能内部处理：
- 分析函数在内部使用完整数据，而呈现简化结果
- 市场趋势推荐过滤掉已存在于投资组合中的股票
- 财务数据压缩保留关键指标同时减小大小

这些优化措施确保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测试通过

测试故障排除

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

数据库连接：确保MongoDB在配置的URI（默认：mongodb://localhost:27017）上运行，并且存在stock_data数据库。
Alpha Vantage API：检查.env文件中的API密钥是否设置并且没有超出速率限制。
数据可用性：某些测试需要MongoDB集合中的现有数据（例如，投资组合持有）。确保您的数据库具有必要的数据。
网络问题：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,