Skip to main content
Glama
finnhub-mcp-server

finnhub-mcp-server

by cyanheads

Version License Docker MCP SDK npm TypeScript Bun

Install in Claude Desktop Install in Cursor Install in VS Code

Framework


Overview

Real-time US stock data from Finnhub: quotes, company fundamentals, earnings, analyst recommendations, and financial news. Look up a company by name, then pull live pricing, valuation, or news for it.

Ticker inputs are trimmed and uppercased; punctuation such as BRK.B is preserved. Earnings calendar filters may be omitted or blank for market-wide results; earnings history and company news require a nonblank symbol. Search queries retain their original spelling, and market news ignores symbol.

Tools

Tool

Description

finnhub_search_symbols

Resolve a company name or ticker, optionally within one exchange. Exact ticker matches rank first.

finnhub_get_quote

Real-time price quote for one US symbol, paired with live market-status so the response states whether the price is live or the prior close, including the returned session and named holiday.

finnhub_get_company

Get a company profile, headline fundamentals, and peers grouped by sub-industry, industry, or sector.

finnhub_get_earnings

Get quarterly EPS surprises or a calendar of releases with EPS and revenue estimates and reported actuals where available.

finnhub_get_news

Financial news in two modes: recent articles for one symbol over a date range (company), or broad market headlines by category (market).

finnhub_get_recommendations

Analyst recommendation trends for one US symbol — strong-buy / buy / hold / sell / strong-sell counts per month, newest first.

Resources

Resource

Description

finnhub://news-categories

The four valid market-news categories (general, forex, crypto, merger) with one-line descriptions.

skill://finnhub-guide/SKILL.md

Agent guide for company and earnings briefings, security identity, quote freshness, and coverage gaps.

The news-category reference mirrors the category enum on finnhub_get_news. The finnhub guide also ships with plugin installs, npm, Docker, and the desktop bundle.

Related MCP server: MCP Finnhub Server

Capability reference

finnhub_search_symbols tool

  • Search by company name or ticker fragment with query (1–20 characters) and limit (1–50, default 10).

  • Exact symbol or displaySymbol matches rank first, ignoring case and retaining Finnhub's order among ties. Likely-US common stocks lead the remaining results. isLikelyUS describes symbol format. Endpoint coverage varies by security.

  • Supply exchange: "US" for US listings. An omitted or blank exchange searches globally. A name search within one exchange can miss an ADR that a ticker search finds.


finnhub_get_quote tool

  • Requires symbol; returns current price, change, session open/high/low, previous close, and an ISO 8601 quote time.

  • priceIsLive distinguishes a live price from the prior close; marketOpen, session, and holiday are nullable when market status is unavailable. Unknown ticker → symbol_not_found; international or paid-only symbol → not_us_or_paid.


finnhub_get_company tool

  • Requires symbol and returns the profile, nullable headline fundamentals, and peers. Set peerGrouping to subIndustry (default), industry, or sector. The response identifies the selected grouping.

  • Failed metrics or peers appear in partial; the profile determines symbol_not_found and not_us_or_paid errors.


finnhub_get_earnings tool

  • history requires a symbol and returns up to limit available quarters of EPS actuals, estimates, and surprises (default 50).

  • calendar accepts an optional symbol and inclusive UTC dates (YYYY-MM-DD, default today through 14 days ahead). Recently reported releases can include EPS and revenue actuals alongside estimates. Missing values are null. Report times include bmo (before open), dmh (during market hours), and amc (after close).

  • Calendar pages contain up to 100 entries (default 50). Pass nextOffset as offset with the same filters to continue. At 1,500 fetched rows, Finnhub may have omitted earlier releases. Narrow the window or filter by symbol to check.


finnhub_get_news tool

  • company requires symbol and accepts a date range (default last 7 days). market uses category: general, forex, crypto, or merger (see finnhub://news-categories).

  • Returns plain-text headlines and summaries, source, ISO 8601 timestamp, and URL, newest first. Pages contain up to 100 articles (default 15).

  • Company mode accepts inclusive UTC dates (YYYY-MM-DD). Follow nextOffset with the same filters for more fetched articles. Finnhub can omit older articles even below 250 results. Check the observed timestamps and query earlier windows for older coverage.


finnhub_get_recommendations tool

  • Per-month strong-buy / buy / hold / sell / strong-sell counts, newest first; history depth depends on Finnhub coverage.

  • limit accepts a positive integer (default 12). The response reports the number of months Finnhub supplied and whether more fetched rows were available.

  • Empty result → no_coverage; it cannot distinguish an invalid symbol from a valid symbol without coverage. International or paid-only symbol → not_us_or_paid.


finnhub://news-categories resource

  • Returns the four valid finnhub_get_news market-mode categories (general, forex, crypto, merger) with one-line descriptions, as application/json

  • Convenience mirror — fully covered by the category enum's .describe() on finnhub_get_news, so tool-only clients lose nothing

  • Live data (quotes, news, earnings) is intentionally not exposed as a resource — it's time-sensitive, so freshness lives only in the tools

Features

The finnhub-guide skill helps agents combine tool results into company and earnings briefings while preserving dates, missing values, and endpoint coverage limits. MCP clients can discover it through skills/list or read its skill://finnhub-guide/SKILL.md resource.

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Finnhub-specific:

  • Single rate-aware Finnhub client — token injected server-side (never a tool input), with timeout and retry calibrated to the 60 req/min free tier

  • Live market-status pairing on quotes so a closed-market price is reported as the prior close, never as live

  • Status classification at the service boundary: 403 → a clear not_us_or_paid domain error, 401 → loud configuration failure at first call (not "no data"), 429/5xx → retried

  • finnhub_get_company fans out profile + metrics + peers in parallel and degrades to partial results when a leg fails

Agent-friendly output:

  • Honest sparsity — every fundamental is nullable and absent values stay null; Finnhub's thinly-covered names are surfaced as-is, never zero-filled or fabricated

  • Two distinct "not available" signals — symbol_not_found (all-zero quote / empty profile sentinel) vs. not_us_or_paid (international or paid-only, HTTP 403). An empty profile can also reflect missing instrument coverage.

  • ETFs, funds, or trusts may lack company profiles, earnings history, or analyst recommendations. Empty responses retain ticker verification guidance and suggest finnhub_get_quote for price data without promising quote availability.

  • Typed error contracts with recovery hints on every failure, plus the isLikelyUS search heuristic so an agent can prioritize likely free-tier symbols

  • Calendar and company-news pages report the fetched count and observed bounds. Each page refetches Finnhub, so new or revised records can shift between requests.

Getting started

This server requires a free Finnhub API key (Dashboard → API key). The free tier covers US equities in real time at 60 req/min.

Each user must obtain their own API key. Use is subject to Finnhub's Terms of Service — the free tier is for personal use only, and redistributing or sharing access to Finnhub data with third parties requires written approval from Finnhub.

Add it to Claude Code:

claude mcp add finnhub-mcp-server -e FINNHUB_API_KEY=your-api-key -- npx -y @cyanheads/finnhub-mcp-server

For other clients, add this to your MCP configuration file:

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

For Docker or a source build, see Running the server.

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

Variable

Description

Default

FINNHUB_API_KEY

Required. Free Finnhub API key from finnhub.io/register. Sent as the token query param; the server fails to start without it.

—

FINNHUB_BASE_URL

Finnhub REST API base URL. Override for local testing or a proxy.

https://finnhub.io/api/v1

MCP_TRANSPORT_TYPE

Transport: stdio or http.

stdio

MCP_HTTP_PORT

Port for the HTTP server.

3010

MCP_HTTP_ENDPOINT_PATH

HTTP endpoint path where the MCP server is mounted.

/mcp

MCP_SESSION_MODE

Session handling: auto, stateful, or stateless. The server declares stateless in src/index.ts, so an unset variable resolves there; .env.example and the Docker image set it explicitly too. An explicit environment value takes precedence.

stateless

MCP_AUTH_MODE

Auth mode: none, jwt, or oauth.

none

MCP_LOG_LEVEL

Log level (RFC 5424: debug, info, notice, warning, error).

info

LOG_TOOL_FAILURE_PAYLOADS

Log failed tool calls' arguments and results, redacted by key name and capped at LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES (default 16384). Secrets inside free-form values are not redacted.

false

STORAGE_PROVIDER_TYPE

Storage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1.

in-memory

OTEL_ENABLED

Enable OpenTelemetry instrumentation (spans, metrics, completion logs).

false

OTEL_EXPORTER_OTLP_ENDPOINT

OTLP base URL for traces (/v1/traces) and metrics (/v1/metrics); signal-specific endpoints override it.

—

OTEL_EXPORTER_OTLP_LOGS_ENDPOINT

Opt-in OTLP log endpoint, used as-is. The base URL does not enable log export.

—

See .env.example for the full list of optional overrides.

Running the server

Local development

Requires Bun v1.4.4 or higher (or Node.js v24+), and a free Finnhub API key.

git clone https://github.com/cyanheads/finnhub-mcp-server.git
cd finnhub-mcp-server
bun install
cp .env.example .env
# Set FINNHUB_API_KEY in .env.
  • Build and run:

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

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

Docker

docker run --rm -e FINNHUB_API_KEY=your-key -p 3010:3010 ghcr.io/cyanheads/finnhub-mcp-server:latest

The image defaults to HTTP transport, stateless session mode, and logs to /var/log/finnhub-mcp-server. For stdio, add -i -e MCP_TRANSPORT_TYPE=stdio to docker run. To build locally, run docker build -t finnhub-mcp-server .; OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Directory

Purpose

src/index.ts

createApp() entry point — registers tools/resources and inits the Finnhub service.

src/config

Server-specific environment variable parsing and validation with Zod.

src/mcp-server/tools

Tool definitions (*.tool.ts). Six tools across symbols, quotes, company, earnings, news, and recommendations.

src/mcp-server/resources

Resource definitions (*.resource.ts). News-categories reference.

src/services/finnhub

Finnhub REST client — auth, typed endpoint methods, retry, and HTTP-status classification.

skills/

Published agent guide, also served as an MCP resource.

tests/

Unit and integration tests mirroring src/.

Development guide

See CLAUDE.md / AGENTS.md for development guidelines and architectural rules. The short version:

  • Handlers throw, framework catches — no try/catch in tool logic

  • Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage

  • Register new tools and resources via the barrels in src/mcp-server/*/definitions/index.ts

  • Wrap the Finnhub API: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      This server provides an interface with the Finnhub API, enabling users to obtain the latest market news, stock market data, basic financials, and recommendation trends for specific stocks.
      9
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides comprehensive financial market data and news through the Finnhub API. Enables real-time stock quotes, company profiles, financial metrics, analyst recommendations, and market news access.
      1
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Provides comprehensive stock analysis tools for real-time market data, technical indicators, and portfolio evaluations using Finnhub and Alpha Vantage. It supports both stdio and Render-compatible HTTP transport modes for flexible integration across environments.
      -
    • F
      license
      A
      quality
      D
      maintenance
      Provides stock market data and analysis tools using the Finnhub API, including stock prices, financial metrics, news, and historical data.
      6
      7
      -