finnhub-mcp-server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 |
| Resolve a company name or ticker, optionally within one exchange. Exact ticker matches rank first. |
| 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. |
| Get a company profile, headline fundamentals, and peers grouped by sub-industry, industry, or sector. |
| Get quarterly EPS surprises or a calendar of releases with EPS and revenue estimates and reported actuals where available. |
| Financial news in two modes: recent articles for one symbol over a date range ( |
| Analyst recommendation trends for one US symbol — strong-buy / buy / hold / sell / strong-sell counts per month, newest first. |
Resources
Resource | Description |
| The four valid market-news categories ( |
| 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) andlimit(1–50, default 10).Exact
symbolordisplaySymbolmatches rank first, ignoring case and retaining Finnhub's order among ties. Likely-US common stocks lead the remaining results.isLikelyUSdescribes 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.priceIsLivedistinguishes a live price from the prior close;marketOpen,session, andholidayare 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
symboland returns the profile, nullable headline fundamentals, and peers. SetpeerGroupingtosubIndustry(default),industry, orsector. The response identifies the selected grouping.Failed metrics or peers appear in
partial; the profile determinessymbol_not_foundandnot_us_or_paiderrors.
finnhub_get_earnings tool
historyrequires a symbol and returns up tolimitavailable quarters of EPS actuals, estimates, and surprises (default 50).calendaraccepts 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 includebmo(before open),dmh(during market hours), andamc(after close).Calendar pages contain up to 100 entries (default 50). Pass
nextOffsetasoffsetwith 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
companyrequiressymboland accepts a date range (default last 7 days).marketusescategory:general,forex,crypto, ormerger(seefinnhub://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). FollownextOffsetwith 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.
limitaccepts 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_newsmarket-mode categories (general,forex,crypto,merger) with one-line descriptions, asapplication/jsonConvenience mirror — fully covered by the
categoryenum's.describe()onfinnhub_get_news, so tool-only clients lose nothingLive 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_paiddomain error, 401 → loud configuration failure at first call (not "no data"), 429/5xx → retriedfinnhub_get_companyfans 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_quotefor price data without promising quote availability.Typed error contracts with recovery hints on every failure, plus the
isLikelyUSsearch heuristic so an agent can prioritize likely free-tier symbolsCalendar 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-serverFor 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 |
| Required. Free Finnhub API key from finnhub.io/register. Sent as the | — |
| Finnhub REST API base URL. Override for local testing or a proxy. |
|
| Transport: |
|
| Port for the HTTP server. |
|
| HTTP endpoint path where the MCP server is mounted. |
|
| Session handling: |
|
| Auth mode: |
|
| Log level (RFC 5424: |
|
| Log failed tool calls' arguments and results, redacted by key name and capped at |
|
| Storage backend: |
|
| Enable OpenTelemetry instrumentation (spans, metrics, completion logs). |
|
| OTLP base URL for traces ( | — |
| 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:httpRun 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:latestThe 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 |
|
|
| Server-specific environment variable parsing and validation with Zod. |
| Tool definitions ( |
| Resource definitions ( |
| Finnhub REST client — auth, typed endpoint methods, retry, and HTTP-status classification. |
| Published agent guide, also served as an MCP resource. |
| Unit and integration tests mirroring |
Development guide
See CLAUDE.md / AGENTS.md for development guidelines and architectural rules. The short version:
Handlers throw, framework catches — no
try/catchin tool logicUse
ctx.logfor request-scoped logging,ctx.statefor tenant-scoped storageRegister new tools and resources via the barrels in
src/mcp-server/*/definitions/index.tsWrap 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 testLicense
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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Unofficial Finnhub MCP — wraps Finnhub Stock API (finnhub.io)
Real-time Yahoo Finance stock/crypto quotes & options, Google Trends, News & Reddit/HN sentiment.
Stock quotes, charts, financials, options, SEC filings, crypto and macro data. Hosted, no API key.
Global equities, ETFs, FX & crypto quotes, OHLCV history, fundamentals, technicals & options Greeks
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceThis 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-
- AlicenseNot gradedqualityBmaintenanceProvides 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.1MIT
- FlicenseNot gradedqualityCmaintenanceProvides 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.-
- FlicenseAqualityDmaintenanceProvides stock market data and analysis tools using the Finnhub API, including stock prices, financial metrics, news, and historical data.67-