Market Data Mcp

market-data-mcp

实时市场数据：为 AI Agent 提供报价、新闻、财报日历和自选列表扫描器，由 Finnhub 提供支持。

为任何 MCP 客户端（Claude Desktop、Claude Code、Agent）提供简洁、统一的市场数据工具， 并能优雅地处理失败。缺失的数据源或需要付费的数据源会返回 “无数据”，绝不会 编造数值。默认输出 Markdown，也可按需输出 JSON。

---

工具

工具	功能	来源	免费版
market_quote	实时价格、涨跌幅、最高/最低价、开盘价/前收盘价	Finnhub /quote	是
market_news	头条新闻前 5 条——公司相关新闻或综合市场新闻	Finnhub /company-news、/news	是
market_calendar	未来 N 天的财报日历（含每股收益/营收预估）	Finnhub /calendar/earnings	是*
market_scan	自选列表扫描器：按绝对涨跌幅对最多 25 个股票代码排序	Finnhub /quote x N	是
market_analyze	综合分析：动量评分 + 新闻催化因素 + 距财报的时间	以上所有来源	是
broker_positions	读取 Alpaca 模拟账户中的未平仓头寸	Alpaca Paper API	可选**

*财报日历于 2026-06-14 进行实时测试：可在 Finnhub 免费版中访问。
**broker_positions 需要在 .env 中设置 ALPACA_API_KEY + ALPACA_SECRET_KEY。未设置时会优雅地降级。

每个工具都会返回 Markdown（易于阅读，默认格式）或 JSON（response_format="json"），供程序使用。

---

实时演示输出（2026-06-14）

market_quote AAPL:
  AAPL: $291.13  (-1.52%  -$4.50)  prev close $295.63

market_scan AAPL,MSFT,NVDA,TSLA:
  Scanned 4/4 symbols. Top mover: TSLA +1.82%

market_calendar days=7:
  20 earnings events in the next 7 days: ACN, KR, MEI ...

market_analyze AAPL:
  Signal: Lean negative  [......##|........] -30/100  confidence 60%
  AAPL: $291.13  -1.52%  → Lean negative [TRIM]
  Catalyst: Apple's iOS 27 surprise could change the AI narrative

---

快速开始

注意： PyPI 上的 market-data-mcp 包是另一个作者开发的不同项目，与本项目无关。 请从源代码安装本项目：

git clone https://github.com/cstamigo-droid/market-data-mcp.git
cd market-data-mcp
python -m venv .venv
.venv\Scripts\activate        # Windows
pip install -r requirements.txt

copy .env.example .env        # edit: add FINNHUB_API_KEY
python tests/test_smoke.py    # live test all 6 tools

在此获取免费的 Finnhub 密钥：https://finnhub.io/register

---

Claude Desktop 配置

将以下内容添加到 claude_desktop_config.json （Windows 上的 %APPDATA%\Claude\，macOS 上的 ~/Library/Application Support/Claude/）， 然后重启 Claude Desktop：

{
  "mcpServers": {
    "market-data-mcp": {
      "command": "python",
      "args": ["-m", "market_data_mcp"],
      "cwd": "C:/path/to/market-data-mcp"
    }
  }
}

如果不使用 venv，请使用系统 Python 路径：

{
  "mcpServers": {
    "market-data-mcp": {
      "command": "C:/Users/YourName/AppData/Local/Python/pythoncore-3.14-64/python.exe",
      "args": ["-m", "market_data_mcp"],
      "cwd": "C:/path/to/market-data-mcp",
      "env": { "PYTHONUTF8": "1" }
    }
  }
}

---

可选：Alpaca 经纪商数据源

broker_positions 工具会读取你的 Alpaca 模拟账户。启用方法：

1. 前往 https://app.alpaca.markets/ → Paper Trading → API Keys
2. 添加到 .env：

   ALPACA_API_KEY=your-key-here
   ALPACA_SECRET_KEY=your-secret-here
   

3. 重启服务。

如果未设置这些密钥，broker_positions 会优雅地返回“未设置密钥”提示。

---

设计理念

• 统一的结果约定。 每个数据源都返回相同的 Result 结构（source、ok、summary、data、score、confidence、error）。大模型无需解析 N 种格式，就能跨所有工具进行推理。
• 优雅降级。 没有数据、需要付费的端点或缺失的密钥都会使数据源返回 Result.failed(...)——绝不会编造数值。Finnhub 对未知代码返回的零价格会被视为“无数据”，而非报价。
• 评分分析。 综合工具 market_analyze 会输出 -100..+100 的方向性评分和置信度，让 Agent 无需阅读文字说明即可进行初步判断。
• TTL 缓存。 按数据源设置的进程内缓存可避免 Agent 在一轮中调用多个工具时（例如依次扫描和分析）频繁请求受速率限制的 API。

---

免责声明

仅供研究和教育用途。数据来自 Finnhub 和 Alpaca，可能存在延迟或不完整。 未经独立核实，切勿将自动化市场数据用于财务决策。

许可证

MIT