mcp-market-research

<p align="center"> <strong>侦察员</strong> — 一个收集和整理金融数据以供AI代理使用的MCP服务器。 </p> <p align="center"> <em>管家交易，侦察员研究。</em> 一个代理交易堆栈的<strong>感知</strong>层 — 它为AI代理（如Claude Code）提供数据，以深入研究任何美国股票、ETF或加密货币资产，来自<strong>免费</strong>的来源。与 <a href="https://github.com/pedrobraiti/agentic-trading-mcp">代理交易MCP</a> （执行）配对。 </p> <p align="center"> <img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python 3.12+"> <img src="https://img.shields.io/badge/license-MIT-green" alt="许可证：MIT"> <img src="https://img.shields.io/badge/tools-62-orange" alt="62个工具"> <img src="https://img.shields.io/badge/status-live--validated-success" alt="状态：实时验证"> </p> > **不是财务建议。** 一个研究和数据收集工具。它<strong>不</strong>下订单，<strong>不</strong>决定购买什么 — 那是代理和`agentic-trading-mcp`的工作。请自担风险。 ## 这是什么 **侦察员** 是一个 **MCP服务器**，暴露了 **62个专为目的而建的工具**，AI代理调用以研究公司或市场 — 报价、基本面、技术面、期权隐含波动率、SEC文件和XBRL财务数据、宏观、新闻、情绪和注意力，以及完整的 **加密货币现货** 层（报价、OHLCV、链上网络健康状况、衍生品资金/开放兴趣、DVOL、DeFi TVL/稳定币/收益率、加密货币宏观和情绪）— 从 **免费、无需密钥** 的数据源收集，并行返回为键入的、结构化的数据。 它是三部分分割的 **感知** 层： - **大脑** — [**维齐尔**](https://github.com/pedrobraiti/vizier-trading-skill)：研究、决策 *什么/何时*，并协调此仓库 + 执行层。 - **感知** — **侦察员** （此仓库）：数据和信息收集。**无状态，仅数据。** - **执行** — [`agentic-trading-mcp`](https://github.com/pedrobraiti/agentic-trading-mcp)：在Interactive Brokers（股票/ETF）和加密货币交易所（现货，通过CCXT）执行。 范围：**美国股票和ETF** 加上 **加密货币现货** （执行端可以交易的内容）。每个工具返回一个`{"ok": ..., "data": ...}`信封，大多数接受一个可选的`as_of`（时间点）日期。 > **侦察员返回数据，而不是报告。** 它为代理提供数字和来源；代理进行分析并生成输出（例如书面报告、图表、PDF）。询问您的代理以 **"使用侦察员工具对股票（例如MU）进行最完整的分析，然后以PDF格式编写报告。"** 代理将调用侦察员的工具，然后自行编写结果。 ## 快速入门 侦察员是一个 **标准MCP服务器** — 将其注册到任何支持MCP的代理/客户端。下例使用Claude Code（最常见的）；步骤相同，但注册命令不同。 ```bash # 1. 安装 git clone https://github.com/pedrobraiti/mcp-market-research.git cd mcp-market-research python -m venv .venv # Windows (PowerShell): & ".venv\Scripts\Activate.ps1" （在策略错误时：Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass） # Linux/macOS: source .venv/bin/activate pip install -e . # 2. （推荐）配置 — SEC EDGAR需要一个可识别的User-Agent cp .env.example .env # 然后设置SCOUT_SEC_USER_AGENT="您的姓名 your@email.com" # 3. 将MCP注册到Claude Code（使用venv的python — 绝对路径） # Windows: claude mcp add scout -- "C:\path\to\mcp-market-research\.venv\Scripts\python.exe" -m scout.server.app # Linux/macOS: claude mcp add scout -- /path/to/mcp-market-research/.venv/bin/python -m scout.server.app ``` 然后，这些工具出现在代理中（在Claude Code中，一个 **新** 会话）。在任何时候，独立于任何代理，验证数据层是否工作： ```bash python -m scout.healthcheck AAPL # 现场烟雾测试（获取一个真实的报价） ``` 然后用自然语言询问代理 — 例如 *"使用侦察员工具对股票进行最完整的分析（例如MU），然后以PDF格式编写报告。"* 代理将调用侦察员的工具，然后自行编写结果。 > **首次调用注意。** 在启动时，MCP服务器会在主线程上预热其数据库（yfinance + ccxt）— 这会增加 **约5秒到启动时间**，但这是故意的：这些库的一次性设置否则会在异步服务器内第一次运行，这会冻结会话的第一个工具调用。有了预热，第一个真正的调用是瞬间的。 **无需API密钥或登录。** 唯一可选的设置是`SCOUT_SEC_USER_AGENT`（SEC政策：可识别的User-Agent）— 没有它，SEC工具（`filings`、`sec_financials`、`filing_search`）会返回一个清晰的“请设置它”的消息；其他一切都无需密钥。 ## 工具（62） **发现 — 查找名称，而不仅仅是查找它们** - `search_symbols(query, limit?)` — 公司名称/部分股票代码 → 符号（入口点）。 - `market_movers(category?, limit?)` — 市场范围内的涨幅/跌幅/最活跃今日。 - `sector_performance(period?, as_of?)` — 每个美国板块（SPDR ETF）的总回报率 — 轮换。 - `etf_holdings(symbol)` — ETF的申报主要持仓和板块权重（打开一个主题）。 - `filing_search(query, forms?, limit?)` — 跨所有SEC文件全文搜索 → 按公司披露的内容（论点 → 名称）。 - `news_search(query, limit?, days?)` — 跨全球媒体的自由文本新闻/事件搜索（**GDELT**）。不详尽 — 它可能会错过资本结构事件（增发、稀释、回购、并购）；交叉检查`filings(form_type="8-K")` / `filing_search`以获取这些。 **公司深入研究** - `company_dossier(symbol, depth?, as_of?)` — **旗舰：** 快照 + 基本面 + 股息 + 技术面 + 收益 + 分析师观点 + 新闻，一并收集（平滑降级）。 - `company_snapshot(symbol, as_of?)` — 价格、当日变动、关键倍数、板块/行业。 - `fundamentals(symbol, period?, as_of?)` — 收入/资产负债表/现金流数据 + 派生利润率。 - `quality_metrics(symbol, as_of?)` — ROE/ROA、利润率、收入和收益增长率以及CAGR。 - `dividends(symbol, as_of?)` — 支付历史、跟踪收益率、增长趋势、中断标志。 - `sec_financials(symbol, as_of?)` — **权威** 年度财务数据来自SEC XBRL（交叉检查`fundamentals`）。 - `filings(symbol, form_type?, limit?, as_of?)` — 最近的SEC EDGAR文件（10-K/10-Q/8-K ...）带有链接。 - `earnings(symbol, as_of?)` — 下一次收益日期 + 历史（估计/实际/惊喜）。 - `ownership(symbol)` — 内幕和机构百分比、主要机构、最近内幕交易、**空头兴趣**（天数覆盖、流通股百分比、百分比变化）。 - `fda_events(company, limit?)` — FDA药物批准 + 召回用于赞助商（**openFDA**）— 制药/生物催化剂。 **价格和技术面** - `price_history(symbol, period?, interval?, as_of?)` — OHLCV条形。 - `technicals(symbol, as_of?)` — SMA（50/200）、EMA（20）、RSI（14）、MACD、ATR（14）、52周范围（原始数字，无判断）。 - `relative_strength(symbols[], benchmark?, period?, as_of?)` — 每个名称相对于基准的表现。 - `options_volatility(symbol, expiry?)` — ATM隐含波动率 + 期权隐含预期变动。 **情绪和注意力** - `news(symbol, limit?)` — 最近的头条新闻（与`extract`配对）。 - `analyst_view(symbol)` — 卖方共识和价格目标（第三方意见，作为数据）。 - `retail_buzz(symbol?, limit?)` — Reddit（WSB/股票）提及热度（**ApeWisdom**）— 零售注意力。 - `wikipedia_attention(article, days?)` — 每日维基百科页面浏览量 — 注意力代理。 **宏观** - `macro_context(as_of?)` — 关键美国宏观数据（**FRED**）+ 一个丰富的`派生`块：利率/曲线/CPI/VIX，以及**美联储净流动性**（WALCL−TGA−RRP）、金融状况（NFCI/STLFSI4）、失业申请、增长预测（GDPNow/CFNAI）、VIX期限结构、5年5年远期、M2同比、SOFR、广泛美元、布伦特-西德、萨姆缺口和衰退概率。 - `cot_positioning(market, weeks?)` — CFTC **交易者承诺：** 投机者与商业净头寸、OI百分比、周环比变化、拥挤z分数。 - `commodity_ratios()` — 宏观指标 **铜/黄金** （Dr. Copper，风险偏好）和 **黄金/白银**，带有z分数（yfinance）。 - `world_macro(country?, codes?)` — 国家级宏观数据（**世界银行**）：GDP、通货膨胀、失业率... - `treasury_data()` — 官方 **美国财政部** 数据：总公共债务、平均利率。 **多符号/投资组合（批量，无状态）** - `compare(symbols[], as_of?)` — 几个名称并排（价格、倍数、利润率、板块）。 - `correlation_matrix(symbols[], period?, as_of?)` — 成对回报相关性（真实多元化）。 - `cointegration_test(symbol_a, symbol_b, lookback_days?)` — Engle-Granger **配对/统计套利：** 对冲比率、残差ADF统计量与临界值、利差z分数、均值回归半衰期。 - `find_cointegrated_pairs(symbols[], lookback_days?, min_correlation?)` — **配对发现：** 筛选一个篮子（相关性预过滤 → ADF测试），按最强到最弱排序的协整对。 - `classify(symbols[], as_of?)` — 每个符号的板块/行业/市值（聚合曝光）。 - `news_digest(symbols[], limit_per_symbol?)` — 一个观察列表的头条新闻，最新的在前。 - `calendar(symbols[], as_of?)` — 即将到来的收益和除息日期，按符号排序。 **加密货币 — 价格、技术面和发现** （符号使用CCXT的`BASE/QUOTE`格式，例如`BTC/USDT`或`BTC`） - `crypto_quote(symbol)` — 现货报价：最后/出价/卖价 + 24小时变动（加密货币`company_snapshot`）。 - `crypto_price_history(symbol, timeframe?, limit?, as_of?)` — OHLCV蜡烛（CCXT，~100个交易所）。 - `crypto_technicals(symbol, as_of?)` — SMA/EMA/RSI/MACD/ATR用于一对（与`technicals`相同的数学运算）。 - `crypto_search(query, limit?)` — 名称/部分符号 → 资产（入口点）。 - `crypto_movers(category?, limit?)` — 涨幅/跌幅/最活跃的货币对（无需符号，无429）。 - `crypto_order_book(symbol, limit?)` — 最佳出价/卖价、价差和深度 — 交易前流动性/滑点读取。 - `crypto_compare(symbols[])` — 几个资产并排（价格、市值、排名、供应）。 - `crypto_correlation_matrix(symbols[], timeframe?, limit?)` — 成对回报相关性（多元化）。 - `crypto_relative_strength(symbols[], benchmark?, timeframe?, limit?)` — 相对于基准的表现（默认为BTC）。 **加密货币 — 基本面、衍生品和情绪** - `crypto_dossier(symbol, depth?)` — **旗舰：** 报价 + 配置文件 + 技术面 + 恐惧和贪婪 + 衍生品 + 链上，一并收集。 - `crypto_asset_profile(symbol)` — 供应（流通/总/最大）、市值、排名、ATH（**Coinpaprika**）。 - `crypto_onchain(asset?)` — 网络健康状况：BTC费用/哈希率（**mempool.space**），ETH gas/地址（**Blockscout**）。 - `crypto_derivatives(symbol)` — 永续资金利率和 **Binance/Bybit/OKX** 的开放兴趣（定位上下文）。 - `crypto_implied_vol(asset?)` — **Deribit** 的DVOL指数（“加密货币VIX”）用于BTC/ETH + 历史。 - `coinbase_premium(symbol?, days?)` — 美国现货（Coinbase）与离岸（Binance）溢价 — 机构/US需求指标（CCXT）。 - `btc_network()` — 比特币基础层：哈希率、矿工收入、 **NVT** （真实、链上结算）+ 现场费用市场和难度（**Blockchain.com** + **mempool.space**）。 - `crypto_fear_greed(days?)` — 加密货币恐惧和贪婪指数（0-100）+ 历史（**alternative.me**）。 - `crypto_buzz(symbol?, limit?)` — Reddit加密货币提及热度（**ApeWisdom** `all-crypto`）。 **加密货币 — DeFi和宏观** - `crypto_macro()` — 总市值、BTC/ETH主导地位、DeFi份额（**CoinGecko**）。 - `crypto_sectors()` — 按类别（L1/DeFi/AI/迷因币...）的性能（**CoinGecko**）。 - `defi_overview(slug?)` — 按链的DeFi TVL，或一个协议的分解（**DefiLlama**）。 - `stablecoin_supply()` — 稳定币流通和锚定状态（**DefiLlama**）— 流动性/系统性风险读取。 - `stablecoin_peg(symbols?, venue?)` — USDT/USDC/DAI相对于1美元的偏差，以基点为单位 + 脱锚标志（**Kraken/CCXT**）— 价格/锚定轴。 - `defi_fees(protocol?)` — 协议 **费用和收入** （现金流基本面）：总 + 前N，或一个协议（**DefiLlama**）。 - `defi_yields(chain?, project?, min_tvl?)` — 收益率/APY池，可筛选（**DefiLlama**）。 **网页** - `extract(url)` — 获取页面 → 清洁、标记高效的降噪Markdown（诚实地报告付费墙/阻止）。 ## 架构 六边形（端口和适配器），镜像`agentic-trading-mcp`：代理仅与MCP工具通信；每个数据源都是一个可交换的适配器，位于端口后面，因此可以在不触及领域的情況下替换或补充免费源。设计原则（无状态、数据而非判断、时间点）在 [DECISIONS.md](DECISIONS.md) 中。 ``` domain/ 模型 + 端口（合约） adapters/ 股票：yfinance、SEC EDGAR、FRED、世界银行、美国财政部、GDELT、ApeWisdom、维基媒体、网页、stooq 加密货币：CCXT、Coinpaprika、alternative.me、mempool.space/Blockscout、Binance/Bybit/OKX、Deribit、 DefiLlama、CoinGecko research/ 元工具，同时调用多个端口（档案、比较、相关性、板块...） analytics.py 源无关的指标数学（SMA/EMA/RSI/MACD/ATR、相关性）— 加密货币复用 server/ MCP服务器（FastMCP）+ 依赖项组合 ``` ## 数据源（全部免费） | 源 | 提供 | 密钥/登录 | |---|---|---| | **yfinance** | 报价、基本面、股息、价格、期权、新闻、分析师、所有权 | 无 | | **SEC EDGAR** | 文件、XBRL财务数据、全文搜索 | 仅User-Agent | | **FRED** | 美国宏观数据（利率、CPI、失业率、VIX） | 无（无密钥CSV） | | **世界银行** | 全球国家级宏观数据 | 无 | | **美国财政部** | 公共债务、平均利率 | 无 | | **GDELT** | 全球新闻/事件搜索 | 无 | | **ApeWisdom** | Reddit提及热度（股票 + 加密货币） | 无 | | **维基媒体** | 维基百科页面浏览量（注意力） | 无 | | **stooq** | 每日价格 — 透明的yfinance备用 | 无 | | **CCXT** | 加密货币现货报价、OHLCV、动向、订单簿（~100个交易所） | 无（公共市场数据） | | **Coinpaprika** | 加密货币供应、市值、排名、ATH、搜索 | 无 | | **alternative.me** | 加密货币恐惧和贪婪指数 | 无 | | **mempool.space / Blockscout** | 链上网络健康状况（BTC费用/哈希率、ETH gas/地址） | 无 | | **Binance / Bybit / OKX** | 永续资金利率和开放兴趣（衍生品背景） | 无（公共） | | **Deribit** | DVOL隐含波动率指数（“加密货币VIX”） | 无 | | **DefiLlama** | DeFi TVL、稳定币供应/锚定、收益率池 | 无 | | **CoinGecko** | 加密货币宏观（主导地位、总市值）和板块表现 | 无（限速） | 付费免费层（Finnhub/FMP）如果需要，可以在同一端口后面插入。 ## 开发 ```bash pip install -e ".[dev]" pytest -q # 145个离线测试 ruff check . # lint ``` ## 许可证 MIT.