finnhub-mcp-server

---

概述

通过 Finnhub 获取实时美股数据，包括报价、公司基本面、财报、分析师建议和财经新闻。使用 finnhub_search_symbols 将公司名称解析为股票代码，然后即可通过任意 MCP 客户端获取其实时价格、估值或新闻。可作为 stdio 进程或本地 Streamable HTTP 服务运行。

工具

工具	描述
finnhub_search_symbols	将公司名称或部分股票代码解析为股票代码，并优先显示最可能的美国股票匹配项。这是使用其他所有工具的入口。
finnhub_get_quote	获取单个美国股票代码的实时价格报价，并结合实时市场状态，说明价格是实时价格还是前一交易日收盘价，同时包含返回的交易时段和节假日名称。
finnhub_get_company	一次调用获取完整的公司信息——简介、核心基本面指标（市盈率、每股收益、利润率、增长情况）和行业同类公司。
finnhub_get_earnings	提供两种财报模式：获取某股票过去几个季度的实际值与预估值及其差异（history），或获取指定日期范围内即将发布的财报，并可选择按股票代码筛选（calendar）。
finnhub_get_news	提供两种财经新闻模式：获取指定日期范围内某股票的近期文章（company），或按类别获取广泛的市场头条新闻（market）。
finnhub_get_recommendations	获取单只美国股票的分析师建议趋势——按月统计强烈买入、买入、持有、卖出和强烈卖出的数量，按时间从新到旧排列。

资源

资源	描述
finnhub://news-categories	四种有效的市场新闻类别（general、forex、crypto、merger），并附有一行说明。

finnhub_get_news 上的 category 枚举已完整涵盖这些类别，因此仅使用工具的客户端不会缺少任何功能。

能力参考

finnhub_search_symbols _工具

• 使用 query（1–20 个字符）和 limit（1–50，默认值为 10）按公司名称或股票代码片段搜索。
• 优先返回可能属于美国普通股的匹配项，并提供 isLikelyUS 股票代码格式启发式判断、匹配总数和结果截断说明。报价和公司资料响应仍是权威信息。

---

finnhub_get_quote _工具

• 必须提供 symbol；返回当前价格、涨跌额、当日开盘价／最高价／最低价、前收盘价，以及 ISO 8601 格式的报价时间。
• priceIsLive 用于区分实时价格和前收盘价；如果无法获取市场状态，marketOpen、session 和 holiday 的值为 null。未知股票代码 → symbol_not_found；国际股票代码或仅限付费使用的股票代码 → not_us_or_paid。

---

finnhub_get_company _工具

• 必须提供 symbol；返回公司资料、可为空的核心财务指标（市盈率、每股收益、52 周价格区间、贝塔系数、股息率、利润率、增长率、净资产收益率）以及同行业公司。
• 获取失败的指标或同行公司会显示在 partial 中；根据公司资料确定 symbol_not_found 和 not_us_or_paid 错误。

---

finnhub_get_earnings _工具

• history 必须提供 symbol，并按从新到旧的顺序返回过去各季度的实际／预估每股收益和业绩意外值。calendar 接受 from / to（默认从今天到 +14 天）和可选的 symbol，返回发布日期、每股收益／营收预估值以及报告时间。
• limit（1–100，默认值为 50）限制返回行数，并说明总数和结果是否被截断。history 未提供股票代码 → missing_symbol；国际股票代码或仅限付费使用的股票代码 → not_us_or_paid。

---

finnhub_get_news _工具

• company 模式必须提供 symbol，并接受日期范围（默认最近 7 天）。market 模式使用 category：general、forex、crypto 或 merger（参见 finnhub://news-categories）。
• 按从新到旧的顺序返回标题、来源、ISO 8601 格式的日期时间、摘要和 URL。limit（1–100，默认值为 15）限制文章数量，并说明总数和结果是否被截断；company 模式未提供股票代码 → missing_symbol；国际股票代码或仅限付费使用的股票代码 → not_us_or_paid。

---

finnhub_get_recommendations _工具

• 按月份统计强烈买入／买入／持有／卖出／强烈卖出评级数量，按从新到旧的顺序排列（通常包含 12–24 个月的历史数据）
• limit（1–24，默认值为 12，即一年）；报告月份总数并说明是否被截断
• 无结果（没有分析师覆盖）→ no_coverage，与无效股票代码相区分；国际股票代码或仅限付费使用的股票代码 → not_us_or_paid

---

finnhub://news-categories _资源

• 以 application/json 格式返回 finnhub_get_news 市场模式下四种有效的类别（general、forex、crypto、merger），并附有一行说明
• 便捷镜像——finnhub_get_news 上 category 枚举的 .describe() 已完整涵盖这些类别，因此仅使用工具的客户端不会缺少任何功能
• 有意不将实时报价、新闻和财报数据公开为资源——这些信息具有时效性，因此只能通过工具获取最新数据

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔的身份验证（none / jwt / oauth）、可切换的存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），并提供结构化日志记录和可选的 OpenTelemetry 跟踪。

Finnhub 专属功能：

• 单个支持速率限制的 Finnhub 客户端——令牌在服务端注入（绝不会作为工具输入），并根据免费套餐的 60 req/min 限制校准超时和重试
• 报价会同时获取实时市场状态，因此休市时报告的价格是前一收盘价，绝不会冒充实时价格
• 在服务边界对状态进行分类：403 → 明确的 not_us_or_paid 领域错误，401 → 首次调用时明确报告配置失败（而不是“无数据”），429/5xx → 自动重试
• finnhub_get_company 会并行获取公司概况、指标和同类公司；任一请求失败时，会降级为返回部分结果

便于 Agent 使用的输出：

• 如实保留稀疏数据——所有基本面数据均可为空，缺失值保持为 null；直接呈现 Finnhub 覆盖数据较少的公司，不会用零填充或捏造数据
• 两种不同的“不可用”信号——symbol_not_found（未知的美国股票代码，通过全零报价／空公司概况哨兵值检测）与 not_us_or_paid（国际市场或仅限付费套餐，HTTP 403）——让 Agent 能够区分并采取相应措施
• 每种失败都有带恢复提示的类型化错误契约；此外还提供 isLikelyUS 搜索启发式，帮助 Agent 优先选择可能属于免费套餐范围的股票代码
• 达到上限的列表会报告总数并说明已截断，让 Agent 知道还有更多数据

开始使用

此服务需要免费的 Finnhub API 密钥（Dashboard → API key）。免费套餐支持实时查询美国股票，速率限制为 60 req/min。

每位用户都必须获取自己的 API 密钥。使用需遵守 Finnhub 服务条款——免费套餐仅供个人使用；如需向第三方重新分发或共享 Finnhub 数据的访问权限，必须事先获得 Finnhub 的书面批准。

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "finnhub-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/finnhub-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FINNHUB_API_KEY": "your-api-key"
      }
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "finnhub-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/finnhub-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FINNHUB_API_KEY": "your-api-key"
      }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "finnhub-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "FINNHUB_API_KEY=your-api-key",
        "ghcr.io/cyanheads/finnhub-mcp-server:latest"
      ]
    }
  }
}

如需使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_SESSION_MODE=stateless MCP_HTTP_PORT=3010 FINNHUB_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

前置要求

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 免费的 Finnhub API 密钥。免费套餐仅支持美国股票，提供实时数据，速率限制为 60 req/min——国际股票代码（任何带交易所后缀的代码，例如 .TO 或 .DE）以及 K 线／外汇接口属于付费套餐，调用时会返回明确错误。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/finnhub-mcp-server.git

2. 进入目录：

cd finnhub-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set FINNHUB_API_KEY

配置

所有配置都会在启动时通过 src/config/server-config.ts 中的 Zod schema 进行验证。主要环境变量：

变量	描述	默认值
FINNHUB_API_KEY	必需。 从 finnhub.io/register 获取免费的 Finnhub API 密钥。作为 token 查询参数发送；未设置时服务无法启动。	—
FINNHUB_BASE_URL	Finnhub REST API 基础 URL。可覆盖此值以进行本地测试或使用代理。	https://finnhub.io/api/v1
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_HTTP_ENDPOINT_PATH	挂载 MCP 服务的 HTTP 端点路径。	/mcp
MCP_SESSION_MODE	会话处理方式：auto、stateful 或 stateless。服务在 src/index.ts 中声明为 stateless，因此未设置变量时会采用该值；.env.example 和 Docker 镜像也会显式设置该值。显式环境变量值优先。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424：debug、info、notice、warning、error）。	info
LOG_TOOL_FAILURE_PAYLOADS	记录失败工具调用的参数和结果，按键名脱敏，并限制为 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（默认值为 16384）字节。自由格式值中的密钥不会被脱敏。	false
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	启用 OpenTelemetry 插桩（跨度、指标、完成日志）。	false
OTEL_EXPORTER_OTLP_ENDPOINT	用于跟踪（/v1/traces）和指标（/v1/metrics）的 OTLP 基础 URL；信号专用端点会覆盖此值。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	可选的 OTLP 日志端点，按原样使用。基础 URL 不会启用日志导出。	—

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t finnhub-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -e FINNHUB_API_KEY=your-key -p 3010:3010 finnhub-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/finnhub-mcp-server。默认会安装 OpenTelemetry 对等依赖项；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具和资源，并初始化 Finnhub 服务。
src/config	使用 Zod 解析并验证服务专用环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。涵盖标的、报价、公司、财报、新闻和推荐的六种工具。
src/mcp-server/resources	资源定义（*.resource.ts）。新闻类别参考。
src/services/finnhub	Finnhub REST 客户端——身份验证、类型化端点方法、重试和 HTTP 状态分类。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md / AGENTS.md。简要说明：

• 处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围的日志，使用 ctx.state 存储租户范围的数据
• 通过 src/mcp-server/*/definitions/index.ts 中的 barrel 文件注册新工具和资源
• 封装 Finnhub API：验证原始数据 → 规范化为领域类型 → 返回输出 schema；切勿编造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。