FinBrain MCP

FinBrain MCP 

需要 Python 3.10+

一个 Model Context Protocol（MCP） 服务，通过简单的工具向 AI 客户端（Claude Desktop、VS Code MCP 扩展等）提供 FinBrain 数据集。 由官方 finbrain-python SDK（v2 API）提供支持。

• 软件包名称：finbrain-mcp

• CLI 入口：finbrain-mcp

• 文档：finbrain.tech/integrations/mcp

---

功能

AI 驱动的价格预测

访问 FinBrain 的机器学习价格预测，涵盖每日（10 天）和每月（12 个月）时间范围。包含均值预测及 95% 置信区间。

新闻与情绪分析

浏览任意股票代码的近期新闻文章，或跟踪随时间变化的每日汇总情绪分数。筛查所有跟踪股票的新闻。

另类数据

• LinkedIn 指标 — 员工人数和关注者趋势，可作为公司健康状况的指标
• App Store 评分 — 面向消费者的公司的移动应用表现数据
• 期权流 — 看跌／看涨比率和成交量，用于判断市场仓位
• Reddit 提及 — 各子版块中的股票代码提及次数，每 4 小时收集一次
• 政府合同 — 来自 USAspending.gov 的美国政府合同授予记录
• 专利申请 — USPTO 授予的专利，按企业受让方映射到股票代码，并包含 CPC 分类

机构与内部人士活动

• 美国国会议员交易 — 众议院代表和参议员披露的股票交易，包含交易日期和公开披露日期（可据此衡量申报延迟）、交易账户的受益所有人（成员、配偶、受抚养子女、共同账户或账户代码），以及按法定 STOCK Act 区间标准化的申报金额，同时保留原始申报内容
• 企业游说 — 游说申报记录，包含注册人、收入、支出和议题代码
• 内部人士交易 — SEC Form 4 申报，显示高管买入和卖出
• 分析师评级 — 华尔街分析师覆盖及目标价变动

---

可获得的功能

• ⚡️ 本地 MCP 服务（不经代理），使用你自己的 FinBrain API 密钥

• 🧰 工具（默认返回 JSON，可选 CSV），支持分页

  • health

  • available_markets、available_tickers、available_regions

  • predictions_by_market、predictions_by_ticker

  • news_by_ticker、news_sentiment_by_ticker

  • app_ratings_by_ticker

  • analyst_ratings_by_ticker

  • house_trades_by_ticker、senate_trades_by_ticker

  • corporate_lobbying_by_ticker

  • insider_transactions_by_ticker

  • linkedin_metrics_by_ticker

  • options_put_call

  • reddit_mentions_by_ticker

  • government_contracts_by_ticker

  • patent_filings_by_ticker

  • recent_news、recent_analyst_ratings

  • screener_sentiment、screener_analyst_ratings、screener_news

  • screener_insider_trading、screener_house_trades、screener_senate_trades

  • screener_put_call_ratio、screener_linkedin、screener_app_ratings、screener_reddit_mentions、screener_government_contracts、screener_patent_filings

• 🧹 结构统一且适合模型处理（我们会规范化原始 API 响应）

• 📱 app_ratings_by_ticker 会返回一个混合的 series——每个日期一行，包含该公司在各商店中规模最大的应用——以及 apps，其中汇总了该公司发布的每个应用（platform、app_id、app_name、observation_count、latest_score、latest_ratings_count）和 app_count。一家公司可能发布许多应用（Apple 在 iOS 上有 140 款），因此根据 series 回答针对单个应用的问题，会把某一款应用误当作覆盖整个公司；请先查看 apps 了解有哪些应用，然后传入 app_id 获取该应用自己的观测数据。摘要按设计不包含观测数据——140 款应用的历史记录会占满上下文。对于早于按应用 ID 归类的数据，行中的 app_id 为 null（平台已知，但应用未知）；如果 app_id 未知，则会返回 available_app_ids，而不是空的 series

• 🏛️ insider_transactions_by_ticker、government_contracts_by_ticker、corporate_lobbying_by_ticker 和 patent_filings_by_ticker 的行中包含 cik——记录对应的公司 SEC 中央索引键，为 10 位、以零填充的字符串（"0000320193"；请保留为文本，前导零是标识符的一部分）；如果记录无法解析实体，则为 null。可用它将行关联到以 SEC 键标识的数据集（EDGAR 文件、13F 持仓）或证券主数据

• 🔑 通过 FINBRAIN_API_KEY 环境变量提供你的 API 密钥（Shell 环境变量或 MCP 客户端的 env 配置块均可）

---

安装

选项 A — 标准安装（pip）

# macOS / Linux / Windows
pip install --upgrade finbrain-mcp

选项 B — 开发安装（可编辑模式）

# from repo root
python -m venv .venv
source .venv/bin/activate # Windows: .\.venv\Scripts\activate
pip install -e ".[dev]"

将生产环境的 pip 与开发环境的 venv 分开使用，以避免路径混淆。

选项 C — Docker

# Build the image
docker build -t finbrain-mcp:latest .

# Run with your API key
docker run --rm -e FINBRAIN_API_KEY="YOUR_KEY" finbrain-mcp:latest

详细的 Docker 使用说明请参阅 DOCKER.md。

---

配置 FinBrain API 密钥

A）在 MCP 客户端配置中设置（推荐／最可靠）

将密钥直接放入客户端使用的 MCP 服务条目中（Claude Desktop 或 VS Code MCP 扩展）。这样可以确保启动的服务能读取密钥，即使系统环境变量未被获取也不受影响。

Claude Desktop（pip 安装）

{
  "mcpServers": {
    "finbrain": {
      "command": "finbrain-mcp",
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

B）环境变量

这种方式也可行，但请注意，设置后必须重启客户端，才能让新值传递给客户端。

# macOS/Linux
export FINBRAIN_API_KEY="YOUR_KEY"

# Windows (PowerShell, current session)
$env:FINBRAIN_API_KEY="YOUR_KEY"

# Windows (persistent for new processes)
setx FINBRAIN_API_KEY "YOUR_KEY"
# then fully quit and reopen your MCP client (e.g., Claude Desktop)

**提示：**如果环境变量方式似乎不起作用（Windows 上很常见，尤其是客户端已经运行时），请使用上面的 config JSON env 方法——这种方式更可靠。

---

运行服务

**注意：**通常无需手动运行服务——MCP 客户端（Claude／VS Code）会自动启动它。只有在手动检查或调试时，才使用以下命令。

• 如果已安装（pip）：

  finbrain-mcp

• 从开发环境的 venv 运行：

  python -m finbrain_mcp.server

无需 MCP 客户端即可快速检查运行状态：

python - <<'PY'
import json
from finbrain_mcp.tools.health import health
print(json.dumps(health(), indent=2))
PY

---

连接 AI 客户端

无需手动启动：Claude Desktop 和 VS Code 会根据你的配置为你启动 MCP 服务。你只需要在快速检查或调试时自行运行 finbrain-mcp。

Claude Desktop

编辑你的配置文件：

• Windows：%APPDATA%\Claude\claude_desktop_config.json

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

• Linux：~/.config/Claude/claude_desktop_config.json

使用 Pip 安装（已发布的软件包）：

{
  "mcpServers": {
    "finbrain": {
      "command": "finbrain-mcp",
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

macOS 提示（完整路径）：

如果 "command": "finbrain-mcp" 无法运行，请查找绝对路径并改用该路径。

which finbrain-mcp    # macOS/Linux
# (Windows: where finbrain-mcp)

使用完整路径的 Claude 配置（macOS 示例）：

{
  "mcpServers": {
    "finbrain": {
      "command": "/full/path/to/finbrain-mcp",
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

开发环境 venv（显式运行模块）：

{
  "mcpServers": {
    "finbrain-dev": {
      "command": "C:\\Users\\you\\path\\to\\repo\\.venv\\Scripts\\python.exe",
      "args": ["-m", "finbrain_mcp.server"],
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

Docker：

{
  "mcpServers": {
    "finbrain": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "finbrain-mcp:latest"],
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

编辑完成后，退出并重新打开 Claude。

VS Code（MCP）

1. 打开命令面板 → “MCP: Open User Configuration”。
   这会打开你的 mcp.json（用户配置文件）。

2. 在 servers 键下添加服务：

   {
     "servers": {
       "finbrain": {
         "command": "finbrain-mcp",
         "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
       }
     }
   }
   

3. 在 Copilot Chat 中启用 Agent Mode，以使用 MCP 工具。

---

可以向 Agent 提出什么请求？

你无需知道工具名称，只需用通俗的语言提出请求。示例：

• 预测

  • “获取 FinBrain 对 AMZN 的每日预测。”
  • “显示 AMZN 的月度预测（12 个月预测期）。”
  • “获取 S&P 500 成分股的全市场每日预测。”

• 新闻

  • “获取 AMZN 的近期新闻文章。”
  • “2025-01-01 至 2025-03-31 期间 AMZN 的新闻情绪如何（上限 50 条）？”
  • “显示所有 S&P 500 股票的最新新闻。”

• 应用评分

  • “获取 2025-01-01 至 2025-06-30 期间 AMZN 的应用商店评分。”

• 分析师评级

  • “列出 AMZN 在 2025 年第 1 季度的分析师评级。”

• 国会议员交易

  • “显示涉及 AMZN 的近期众议院交易。”
  • “显示涉及 META 的近期参议院交易。”
  • “对于 NVDA 的众议院交易，每位议员用了多长时间才披露交易？”
  • “近期哪些参议院交易是通过配偶或联名账户进行的？”

• 企业游说

  • “显示 AAPL 的企业游说申报记录。”
  • “MSFT 在 2024 年（2024-01-01 至 2024-12-31）聘用了哪些游说公司？”

• 内部人交易

  • “AMZN 的近期内部人交易？”

• LinkedIn 指标

  • “获取 AMZN 的 LinkedIn 员工人数和关注者数量（过去 12 个月）。”

• 期权（看跌／看涨）

  • “过去 60 天 AMZN 的看跌／看涨比率是多少？”

• Reddit 提及

  • “显示过去一周 TSLA 在 Reddit 上的提及情况。”
  • “哪些 subreddit 最常讨论 AAPL？”

• 政府合同

  • “显示 LMT 在 2025 年获得的政府合同。”
  • “哪些公司获得的政府合同金额最大？”

• 专利申请

  • “显示 AAPL 的近期专利申请。”
  • “近期哪些公司获得的专利授权数量最多？”

• 筛选器（跨股票代码）

  • “筛选 S&P 500 股票的情绪。”
  • “显示所有股票的最新分析师评级。”
  • “筛选所有股票代码的内部人交易（上限 50 条）。”
  • “筛选 US 地区股票的 LinkedIn 数据。”
  • “目前 Reddit 上提及次数最多的股票代码有哪些？”
  • “目前哪些公司提交的专利申请最多？”

• 可用性

  • “有哪些市场可用？”
  • “列出每日预测范围内的股票代码。”
  • “显示可用的地区及其市场。”

注意

• 日期格式：YYYY-MM-DD。
• 时间序列端点默认返回最新的 N 个数据点——说“limit 200”可获取更多。
• 预测期限：每日（10 天）或每月（12 个月）。
• 说“as CSV”即可接收 CSV，而非 JSON。
• 无需指定市场，直接使用股票代码即可。

---

开发

# setup
python -m venv .venv
source .venv/bin/activate # Windows: .\.venv\Scripts\activate
pip install -e ".[dev]"  # run tests pytest -q

项目结构（概览）

finbrain-mcp
├─ README.md
├─ pyproject.toml
├─ LICENSE
├─ .github/
├─ examples/
├─ src/
│  └─ finbrain_mcp/
│     ├─ __init__.py
│     ├─ server.py                # MCP server entrypoint
│     ├─ registry.py              # FastMCP instance
│     ├─ client_adapter.py        # wraps finbrain-python; caches SDK client; calls normalizers
│     ├─ auth.py                  # resolves API key (env var)
│     ├─ utils.py                 # helpers (latest_slice, CSV, DF->records)
│     ├─ normalizers/             # endpoint-specific shapers
│     └─ tools/                   # MCP tool functions (registered & testable)
└─ tests/                         # pytest suite with a fake SDK

---

故障排除

• ENOENT（无法启动服务）

  • 客户端配置中的路径错误。请使用虚拟环境的准确路径：

    • …\.venv\Scripts\python.exe + ["-m","finbrain_mcp.server"]，或

    • …\.venv\Scripts\finbrain-mcp.exe

• FinBrain API key not configured

  • 将 FINBRAIN_API_KEY 放入客户端的 env 配置块中，或

  • 执行 setx FINBRAIN_API_KEY "YOUR_KEY"，并彻底重启客户端。

• 混用开发版和生产版安装

  • 将 pip（生产版）和 venv（开发版）分开使用。

  • 在配置中，选择其中一种，不要同时使用两种。

---

许可证

MIT（见 LICENSE）。

---

致谢

• 基于 Model Context Protocol 和 FastMCP 构建。

• 使用官方 finbrain-python SDK。

---

© 2026 FinBrain Technologies — 为量化社区倾心打造 ❤️。