financial-hub-mcp

Financial Hub MCP Server

一个用于聚合金融数据的 TypeScript MCP 服务。可将任何兼容 MCP 的 AI 助手连接到 SEC EDGAR 文件、XBRL 财务报表、FRED 经济指标和实时市场数据，并内置 XBRL 规范化、事实去重、计算分析、股票筛选和速率限制保护。

核心概念

SEC EDGAR

所有 SEC EDGAR 数据均直接来自 SEC 的免费公共 API data.sec.gov。无需 API 密钥。服务会自动处理：

• XBRL 概念解析 — 不同公司会使用不同的 XBRL 标签表示同一指标。服务会对 20 多个财务概念进行规范化处理（例如，revenue 会解析为 Revenues、RevenueFromContractWithCustomerExcludingAssessedTax、SalesRevenueNet 和其他 11 种变体）。
• 事实去重 — 原始 XBRL 数据包含来自重叠的 10-K/10-Q 文件及修订文件的重复值。服务会将这些值合并为每个财年期间一个整洁的值。
• 速率限制 — SEC 将请求频率限制为每秒 10 次。采用令牌桶速率限制器，并设置有界排队（最多 50 个待处理请求，超时时间为 30 秒），以防止 IP 被封禁。

FRED

FRED（Federal Reserve Economic Data）提供来自 100 多个来源的 800,000 多条时间序列。需要从 fred.stlouisfed.org 获取免费 API 密钥。速率限制为每分钟 120 次请求（通过每秒 2 个请求的令牌桶实现）。其中包含一个精选目录，涵盖 9 个类别、约 50 项重要经济指标，可在不调用 API 的情况下浏览。

Finnhub 市场数据

通过 Finnhub API 获取实时股票报价、公司概况、市场新闻、内幕交易和财务指标。免费套餐每秒提供 30 次 API 调用，无需信用卡。服务将速率限制为每秒 25 次请求，以确保低于阈值。报价绝不缓存（价格过时比不缓存更糟），而公司概况（24 小时）、新闻（5 分钟）和财务指标（1 小时）则使用相应的 TTL。

缓存

带有 TTL 过期机制的内存 LRU 缓存可减少冗余 API 调用：

缓存	TTL	最大条目数	负载大小
公司事实	1 小时	10	每个 20-50 MB
公司提交文件	1 小时	30	每个约 50 KB
公司股票代码	24 小时	1	约 3 MB
FRED 系列元数据	6 小时	100	每个约 1 KB
FRED 观测值	1 小时	50	每个约 5 KB
市场概况	24 小时	50	每个约 1 KB
市场新闻	5 分钟	10	每个约 5 KB
内幕交易	1 小时	30	每个约 3 KB
基本财务数据	1 小时	30	每个约 2 KB

淘汰策略为 LRU——读取时会提升频繁访问的条目，因此容量已满时会淘汰最近最少使用的条目。每次写入时都会主动清理过期条目。

API

工具

• search_companies

  • 按名称或股票代码搜索在 SEC 注册的公司
  • 输入：query（字符串）
  • 返回匹配的公司名称、股票代码和 CIK 编号

• get_company_filings

  • 获取公司的近期 SEC 文件
  • 输入：
    • cik（字符串）：SEC 的公司唯一标识符
    • formType（字符串，可选）：按文件类型筛选（10-K、10-Q、8-K、DEF 14A）
  • 返回文件元数据：文件类型、日期和文档链接

• get_financial_metric

  • 获取去重后的财务指标历史值，并进行趋势分析
  • 输入：
    • cik (string)：公司 CIK 编号
    • concept (string)：易读名称或原始 XBRL 标签
    • taxonomy (string, optional)：XBRL 分类标准（默认值：us-gaap）
    • annualOnly (boolean, optional)：仅返回年度数据点
  • 接受易读名称：revenue、net_income、gross_profit、operating_income、eps、total_assets、total_liabilities、stockholders_equity、cash、long_term_debt、current_assets、current_liabilities、operating_cash_flow、capex、shares_outstanding
  • 也接受原始 XBRL 标签：Revenues、NetIncomeLoss、Assets 等
  • 返回去重后的值（每个财年期间一个）、同比增长率和趋势方向

• get_financial_summary

  • 获取包含计算所得比率的全面财务快照
  • 输入：cik (string)
  • 返回最新指标：收入、净利润、资产、负债、权益、现金、债务、EPS、经营现金流、自由现金流
  • 计算所得比率：利润率、债务权益比、流动比率、ROE、ROA
  • 所有值均从最近的年度申报文件中去重得出

• get_company_facts_summary

  • 获取公司所有可用 XBRL 数据的精简索引
  • 输入：
    • cik (string)：公司 CIK 编号
    • limit (number, optional)：返回的概念数量上限（默认值 40，最大值 100）
  • 返回概念名称、最新值和数据点数量，而非完整时间序列
  • 在深入查询具体指标之前，可用此工具了解有哪些数据可用

• analyze_financials

  • 深入分析财务状况，计算比率、增长指标并进行健康度评分
  • 输入：cik (string)
  • 返回：
    • 财务比率：利润率、毛利率、营业利润率、ROE、ROA、债务权益比、流动比率
    • 增长分析：同比增长率、3 年和 5 年 CAGR、趋势检测
    • 综合健康等级（A-F）及说明因素
  • 内部使用 Promise.allSettled，单项指标查询失败不会导致分析崩溃

• compare_companies

  • 并排比较 2-5 家公司的财务状况
  • 输入：ciks (string[], 2-5 个 CIK 编号)
  • 比较收入、利润、资产、现金、EPS、自由现金流、比率和健康度评分
  • 按收入、盈利能力、增长和整体健康度确定领先者
  • 单家公司查询失败会单独处理，仍会返回部分比较结果

• search_filings

  • 对 SEC EDGAR 的所有申报文件进行全文搜索，并支持分页
  • 输入：
    • query (string)：搜索词
    • forms (string, optional)：以逗号分隔的表格类型
    • startDate (string, optional)：YYYY-MM-DD
    • endDate (string, optional)：YYYY-MM-DD
    • limit (number, optional)：每页结果数（默认值 20，最大值 50）
    • offset (number, optional)：分页时跳过的结果数
  • 返回结果数组和总命中数，以供分页
  • 搜索 2001 年以来任何申报文件的全文

• screen_stocks

  • 按交易所、行业、名称和财务健康状况筛选在 SEC 注册的公司
  • 输入：
    • exchange (string, optional)：按交易所筛选（例如 NYSE、Nasdaq）
    • industry (string, optional)：SIC 行业组（technology、finance、healthcare、energy、manufacturing、retail、transportation、utilities、services、public_admin）
    • nameContains (string, optional)：按公司名称进行不区分大小写的子字符串匹配
    • minHealthScore (number, optional)：财务分析得出的最低健康等级（0-100）
    • limit (number, optional)：结果数量上限（默认值 20，最大值 50）
  • 两阶段筛选：首先在客户端即时筛选 10,000 多家公司，然后可选通过 SEC API 深入筛选行业和健康度指标

• get_corporate_events

  • 获取近期 8-K 公司事件，并进行重要性分类
  • 输入：
    • cik（字符串）：公司 CIK 编号
    • significance（字符串，可选）：按重要性筛选，可选值为 high、medium 或 low
    • limit（数字，可选）：事件数量上限（默认 15，最多 50）
  • 将 25 种 SEC 8-K 项目编号归类为易读类别，并标注重要性级别
  • 高重要性：CEO 变更、并购、破产、重大协议、审计师变更
  • 中等重要性：财报发布、离职、资产出售、修订
  • 使用现有提交数据，无需额外 API 调用

• search_economic_data

  • 在 FRED 数据库中搜索经济数据序列
  • 输入：query（字符串）
  • 返回序列 ID、标题、频率和单位
  • 将返回的序列 ID 用于 get_economic_data

• get_economic_data

  • 获取 FRED 经济数据序列的时间序列观测值
  • 输入：
    • seriesId（字符串）：FRED 序列 ID
    • startDate（字符串，可选）：YYYY-MM-DD
    • endDate（字符串，可选）：YYYY-MM-DD
  • 常用序列：GDP、CPIAUCSL（CPI）、UNRATE（失业率）、FEDFUNDS、DGS10（10 年期国债）、SP500、MORTGAGE30US

• get_stock_quote

  • 从 Finnhub 获取实时股票报价
  • 输入：symbol（字符串）：股票代码（例如 AAPL、MSFT、GOOGL）
  • 返回当前价格、日涨跌额、涨跌幅、当日最高价/最低价、开盘价和前收盘价
  • 实时数据，不会缓存

• get_market_news

  • 获取最新财经新闻标题
  • 输入：
    • symbol（字符串，可选）：公司相关新闻的股票代码。省略则获取一般市场新闻
    • category（字符串，可选）：general、forex、crypto、merger（仅适用于一般新闻）
  • 最多返回 20 篇文章，包括标题、摘要、来源、URL 和日期时间

• get_insider_transactions

  • 获取公司的近期内部人士交易活动
  • 输入：symbol（字符串）：股票代码（例如 AAPL、TSLA）
  • 返回内部人士姓名、股份数量、交易日期、价格和买入/卖出代码
  • 交易代码：P = 买入，S = 卖出，M = 期权行权，A = 授予/奖励，G = 赠与，F = 预扣税款

• get_company_overview

  • 获取综合公司概览，汇总公司简介、市场指标和同行公司信息
  • 输入：symbol（字符串）：股票代码（例如 AAPL、MSFT）
  • 返回名称、交易所、行业、市值、市盈率、Beta、52 周区间、每股收益、股息率和同行股票代码
  • 合并来自 4 次并行 Finnhub API 调用的数据（公司简介、财务数据、同行公司、报价）

资源

• sec://company/{ticker}

  • 包含 SEC 元数据和近期申报文件的公司简介
  • 包括：名称、CIK、股票代码、交易所、SIC 代码、财年结束日期和最近 10 份申报文件
  • 可通过任何支持资源的 MCP 客户端浏览

• fred://catalog/{category}

  • 按类别浏览精选的 FRED 经济指标
  • 类别：gdp、labor、inflation、rates、housing、markets、money、trade、consumer
  • 返回序列 ID、标题、频率和说明，无需 API 调用

• fred://indicator/{seriesId}

  • 查看 FRED 指标详情及最新观测值
  • 返回目录中的序列元数据以及最近 10 个数据点
  • 拉取完整时间序列前，可用此资源查看具体指标

提示词

• financial_analysis

  • 引导式公司财务健康状况分析
  • 输入：ticker（字符串）
  • 分析营收趋势、盈利能力、资产负债表状况和风险评估

• peer_comparison

  • 并列比较两家公司
  • 输入：ticker1（字符串）、ticker2（字符串）

• economic_overview

  • 当前美国经济状况仪表板
  • 无需输入
  • 获取 GDP、失业率、CPI、联邦基金利率、国债收益率和抵押贷款利率

工具注释

所有工具都设置了 MCP ToolAnnotations，以便安全地组合 Agent：

提示	值	原因
readOnlyHint	true	所有工具均为只读，不会修改数据
destructiveHint	false	不会销毁数据
idempotentHint	true	相同的输入会产生相同的输出
openWorldHint	true	所有工具都会调用外部 API

错误处理

所有工具在失败时都会返回符合 MCP 规范的错误封装，其中 isError: true：

{
  "content": [{ "type": "text", "text": "SEC EDGAR request failed: 404 Not Found" }],
  "isError": true
}

这样，大模型就能收到语义明确的错误消息、修正参数并重试，而不是收到会中断 Agent 循环的不透明传输层 JSON-RPC 错误。

在 Claude Desktop 中使用

将以下内容添加到你的 claude_desktop_config.json：

NPX

{
  "mcpServers": {
    "financial-hub": {
      "command": "npx",
      "args": ["-y", "financial-hub-mcp"],
      "env": {
        "FRED_API_KEY": "your-free-api-key",
        "SEC_USER_AGENT_EMAIL": "[email protected]",
        "FINNHUB_API_KEY": "your-free-api-key"
      }
    }
  }
}

在 VS Code 中使用

如需手动安装，请将配置添加到用户级 MCP 配置文件中。打开命令面板（Ctrl + Shift + P），运行 MCP: Open User Configuration，然后添加：

NPX

{
  "servers": {
    "financial-hub": {
      "command": "npx",
      "args": ["-y", "financial-hub-mcp"],
      "env": {
        "FRED_API_KEY": "your-free-api-key",
        "SEC_USER_AGENT_EMAIL": "[email protected]",
        "FINNHUB_API_KEY": "your-free-api-key"
      }
    }
  }
}

如需了解 VS Code 中 MCP 配置的更多详情，请参阅 VS Code 官方 MCP 文档。

环境变量

变量	必需	描述
SEC_USER_AGENT_EMAIL	是	用于遵守 SEC EDGAR API 规定的电子邮件地址。如果未设置，服务将立即退出——SEC EDGAR 会禁止缺少 User-Agent 标头或使用通用 User-Agent 标头的请求。
FRED_API_KEY	FRED 工具需要	从 fred.stlouisfed.org 获取的免费 32 字符密钥。未设置时服务仍会启动，但 FRED 工具在运行时会失败并显示明确的错误消息。
FINNHUB_API_KEY	市场工具需要	从 finnhub.io 获取的免费 API 密钥。股票报价、市场新闻、内幕交易和公司概览均需要此密钥。未设置时服务仍会启动，但市场工具在运行时会失败。

架构

src/
├── index.ts              # Entry point — startup validation, MCP server init
├── rate-limiter.ts       # Token-bucket rate limiter with bounded queue + timeout
├── cache.ts              # In-memory TTL cache with proactive eviction
├── edgar/
│   ├── client.ts         # SEC EDGAR HTTP client (rate-limited, cached)
│   ├── tools.ts          # MCP tool registrations (12 tools, isError envelopes)
│   ├── resources.ts      # MCP resource templates (company profiles)
│   ├── xbrl.ts           # XBRL fact deduplication, growth, trend detection
│   ├── concepts.ts       # Concept alias normalization (20+ financial concepts)
│   ├── analytics.ts      # Computed ratios, health scoring, company comparison
│   ├── events.ts         # 8-K corporate event classification (25 item types)
│   └── screening.ts      # Stock screening by exchange, industry, health score
├── fred/
│   ├── client.ts         # FRED HTTP client (rate-limited, cached)
│   ├── tools.ts          # FRED MCP tool registrations
│   ├── catalog.ts        # Curated catalog of ~50 essential FRED indicators
│   └── resources.ts      # FRED MCP resource templates (catalog + indicators)
├── market/
│   ├── client.ts         # Finnhub HTTP client (rate-limited, cached)
│   └── tools.ts          # Market data MCP tool registrations (4 tools)
└── prompts.ts            # Financial analysis prompt templates

数据流水线

SEC EDGAR 的原始 XBRL 数据会经过多个处理阶段：

1. 限速获取 — 令牌桶确保不会超过 SEC 每秒 10 次请求的限制。待处理请求超过 50 个或等待时间超过 30 秒时，队列会拒绝请求。
2. 缓存 — 公司事实缓存 1 小时，最多缓存 15 条，以避免大型负载导致内存溢出。
3. 概念解析 — 将 revenue 等易读名称映射到 us-gaap 分类体系中所有已知的 XBRL 标签变体。
4. 去重 — 将重叠的 10-K/10-Q/修订版数据合并为每个财务期间一条记录。优先采用 10-K 而非 10-Q，并优先采用较新的申报日期。
5. 分析 — 根据清理后的数据计算增长率、CAGR、财务比率和健康评分。
6. 序列化 — 输出精简 JSON，以尽量减少上下文窗口的使用量。

从源代码构建

git clone https://github.com/ykshah1309/financial-hub-mcp.git
cd financial-hub-mcp
npm install
npm run build

在本地运行：

FRED_API_KEY=your-key SEC_USER_AGENT_EMAIL=your-email FINNHUB_API_KEY=your-key node dist/index.js

贡献

欢迎提交拉取请求。请参阅 CONTRIBUTING.md，了解开发流程、提交风格和 PR 检查清单。参与即表示你同意遵守行为准则。

安全

请私下报告安全问题，详情见 SECURITY.md。请勿公开提交漏洞或凭据泄露相关问题。

更新日志

请参阅 CHANGELOG.md 了解发行说明。

许可证

MIT，详见 LICENSE。

徽章