股票研究MCP服务器
一个老练的 多代理模型上下文协议（MCP）服务器 用于全面的股票研究和分析。使用自然语言查询任何部门或行业，并获得美国证券交易委员会文件和实时市场数据支持的即时详细分析。
✨ 主要亮点
- 🤖 多代理架构：三个专业的人工智能代理协同工作进行全面分析
- 🔍 语义搜索：ChromaDB拥有8000多份公司SEC文件，支持自然语言查询
- 🚀 零配置：首次使用时自动设置ChromaDB，并进行流媒体播放
- 🌐 双接口：通过克劳德桌面（MCP）或Gradio网络界面使用
- 📊 实时数据：与雅虎财经和OpenAI整合，以获取当前市场洞察
- ⚡ 快速高效：初始设置后分析查询的延迟约为355ms
📑 目录
🚀 特性
🤖 多代理系统
三位专业代理携手合作：
- 股票搜索代理
- 通过ChromaDB对SEC文件进行语义搜索 - 雅虎财经API独家直播数据 （无模拟数据） - 使用自然语言查询查找公司
- 股票分类代理
- 按价格范围对股票进行分组 - 高：>100美元，中：10-100美元，低：\$100 │ │ • Medium: $10-$100 │ │ • Low: $100) ├── MEDIUM ($10-$100) └── LOW ( List[Stock]: api_key = os.getenv("ALPHA_VANTAGE_API_KEY") url = f"https://www.alphavantage.co/query?function=SECTOR&apikey={api_key}"
response = requests.get(url) data = response.json()
# Parse and return Stock objects return stocks
**推荐API：**
- [阿尔法Vantage](https://www.alphavantage.co/) -免费套餐可用
- [雅虎财经API](https://pypi.org/project/yfinance/) -Python库
- [财务建模准备](https://financialmodelingprep.com/) -综合数据
- [Polygon.io](https://polygon.io/) -实时数据
**其他新闻来源：**
- [新闻API](https://newsapi.org/) -获取更广泛的新闻报道
- [Finnhub](https://finnhub.io/) -用于财经新闻聚合
- [阿尔法Vantage新闻](https://www.alphavantage.co/) -获取替代新闻推送
注意：该系统已经通过yfinance库从雅虎财经获取了真实新闻。
**其他事件源：**
- [阿尔法Vantage活动](https://www.alphavantage.co/) -有关其他收入日历
- [Finnhub日历](https://finnhub.io/) -用于IPO和经济日历
注意：该系统已经从雅虎财经获取了实际收益日期、股息计划和除息日期。
### 环境变量
创建一个 `.env` 文件：
.env
ALPHA_VANTAGE_API_KEY=your_key_here NEWS_API_KEY=your_key_here FINNHUB_API_KEY=your_key_here POLYGON_API_KEY=your_key_here
加载代码：
from dotenv import load_dotenv load_dotenv()
安装python dotenv：
pip install python-dotenv
## 📊 示例输出
系统生成以下格式的综合报告：
================================================================================ STOCK ANALYSIS REPORT - TECHNOLOGY SECTOR ================================================================================ Total Stocks Analyzed: 10
──────────────────────────────────────────────────────────────────────────────── HIGH-VALUE STOCKS (Price > $100) ────────────────────────────────────────────────────────────────────────────────
📊 AAPL - Apple Inc. Price: $175.43 | Change: 1.35% Trend: bullish
📰 Recent News (3): • Apple reports quarterly earnings [positive] • Analysts upgrade AAPL rating [positive]
📅 Upcoming Events (3): • Earnings Call - 2025-12-19 [high impact] • Dividend Payment - 2025-12-04 [medium impact]
💡 Recommendation: Stock shows positive momentum. News sentiment is generally positive...
## 🛠️ 故障排除
### ChromaDB问题
**问题：找不到ChromaDB/没有退货**
✅ **解决：**
1. Verify ChromaDB exists
ls -la output/chroma_db/
2. Check environment variable
echo $CHROMA_PERSIST_DIR
3. Rebuild if needed
python src/sector/builder.py
4. Use absolute path in MCP config
CHROMA_PERSIST_DIR="/Users/pradeepsahu/dev_data/StockSearhMCP/output/chroma_db"
**问题：ChromaDB查询错误：“预期包含项目为…”**
✅ **状态：已修复** 最新版本
- ChromaDB `query()` 总是回来 `ids` 默认情况下
- 删除最新代码 `"ids"` 从 `include` 参数
- 更新自 `src/stock_research_mcp/agents/sector_ticker_fetcher.py` 如有需要
### MCP连接问题
**问题：Claude Desktop未显示该工具**
✅ **完整检查表：**
1. **配置位置** （macOS）：
# Must be in user home, not system /Library ~/Library/Application Support/Claude/claude_desktop_config.json
1. **绝对Python路径**:
"command": "/Users/pradeepsahu/dev_data/StockSearhMCP/.venv/bin/python"
❌ 不是： `"python"` 或 `"python3"`
1. **有效的API密钥**:
"OPENAI_API_KEY": "sk-proj-actual-key-here"
❌ 不是： `"your-openai-api-key-here"`
1. **JSON语法**:
- 验证时间https://jsonlint.com
- 没有尾随逗号
- 正确的引号和括号
1. **完全重新启动**:
# Quit (Cmd+Q), wait 5 sec, reopen
1. **检查连接**:
- 寻找🔌 绿色插头图标（克劳德桌面左下角）
- 单击查看连接的服务器列表
1. **查看日志**:
tail -f ~/Library/Logs/Claude/mcp*.log
**手动测试服务器：**
cd /Users/pradeepsahu/dev_data/StockSearhMCP source .venv/bin/activate python -m stock_research_mcp.server
Should show: "Stock Research MCP Server starting..."
Press Ctrl+D to exit
**Claude中的强制工具使用：**
- ❌ 坏：“告诉我科技股的情况”（克劳德用常识）
- ✅ 好：“分析科技股”（强制工具调用）
- ✅ 明确：“使用analyze_sector工具进行医疗保健”
### 安装和服务器问题
**问题：服务器无法启动**
Check Python version (need 3.10+)
python --version
Activate virtual environment
source .venv/bin/activate
Reinstall dependencies
pip install -e .
Verify OpenAI key
echo $OPENAI_API_KEY
**问题：导入错误**
Check PYTHONPATH in MCP config
echo $PYTHONPATH
Verify all files exist
ls -la src/stock_research_mcp/agents/
Check ChromaDB access
ls -la output/chroma_db/
### 生成器脚本问题
**问题：SEC 403禁止错误**
✅ 设置符合SEC的用户代理：
export SEC_API_USER_AGENT="YourCompany contact@example.com"
**问题：OpenAI API错误**
✅ 解决：
Verify key is valid
echo $OPENAI_API_KEY
Check quota/billing
Visit: https://platform.openai.com/usage
**问题：下载超时**
✅ 减少工人：
export MAX_WORKERS="4" # Instead of 8 export BATCH_SIZE="32" # Instead of 64
### Gradio接口问题
**问题：端口7860已在使用中**
Kill existing process
lsof -ti:7860 | xargs kill -9
Or change port in gradio_app.py
server_port=8080 # Use different port
**问题：缺少Gradio**
pip install gradio
Or
uv pip install gradio
**问题：OpenAI密钥不起作用**
检查 `.env` 文件：
cat .env
Should have: OPENAI_API_KEY=sk-proj-actual-key
## 🔄 更新ChromaDB索引
### 何时重建
在以下情况下重建ChromaDB索引：
- 新公司向美国证券交易委员会提交文件
- 您想刷新最新的10-K/10-Q文件
- 索引已损坏
- 你想扩展到更多的公司
### 如何更新
Option 1: Full rebuild (deletes old data)
rm -rf output/chroma_db/ python src/sector/builder.py
Option 2: Incremental update (builder will add/update)
python src/sector/builder.py
### 自定义索引
**包括更多/更少的公司**:
编辑 `src/sector/fetch_tickers.py` 按市值、交易所等进行筛选。
**添加特定股票代码**:
创建自定义股票代码列表JSON文件并修改 `builder.py`
**更改归档类型**:
编辑 `candidates` 在中列出 `src/sector/fetch_filings.py`:
candidates = ["10-K", "20-F", "S-1", "10-Q"] # Modify as needed
## 🤝 贡献
欢迎投稿！需要改进的地方：
- \[\]与真实金融API集成
- \[\]先进的技术分析指标
- \[\]股票预测的机器学习
- \[\]更复杂的情绪分析
- \[\]历史数据分析
- \[\]投资组合管理功能
- \[\]实时价格更新
- \[\]其他行业和国际市场
## 📄 许可证
MIT许可证
## ⚠️ 免责声明
**重要**：此工具仅用于教育和研究目的。虽然该系统使用雅虎财经的真实市场数据，但投资建议是通过算法生成的，应该 **非** 作为实际投资决策的唯一依据。
- 始终进行自己的研究
- 咨询合格的财务顾问
- 过去的表现并不能保证未来的结果
- 投资涉及风险，包括本金损失
## 📚 资源
- [MCP文件](https://modelcontextprotocol.io/)
- [Pydantic文档](https://docs.pydantic.dev/)
- [Python异步指南](https://docs.python.org/3/library/asyncio.html)
## 💡 提示
1. **仅限实时数据** -该系统仅使用雅虎财经进行实时价格、新闻和活动（没有模拟数据）
1. **速率限制** -雅虎金融通过yfinance有内置的利率限制
1. **缓存** -考虑为频繁查询的股票缓存API响应
1. **错误处理** -如果雅虎财经数据不可用，系统会正常失败（无法回退到模拟数据）
1. **日志记录** -所有操作都记录到 `logs/` 调试目录
______________________________________________________________________
内置于❤️ 使用Python和模型上下文协议