Tools

Six tools, name-first: finnhub_search_symbols resolves a company name to a US ticker, then the other five work from that symbol — a live quote, full company context, earnings, news, and analyst consensus.

finnhub_search_symbols

Resolve a company name, partial name, or ticker fragment to Finnhub stock symbols. Run this first when you have a name, not a ticker — the rest of the surface needs a symbol.

• Full-text match across symbols and descriptions; likely-US Common Stock matches surfaced first
• query accepts 1–20 characters; use a shorter company name or ticker fragment when needed
• Each result carries isLikelyUS, a symbol-format heuristic: plain tickers and .A/.B class shares are likely US, while exchange suffixes such as .SS, .T, and .L are not. Quote and profile responses remain authoritative
• limit (1–50, default 10); reports the total match count and discloses truncation when more matched than returned

finnhub_get_quote

Real-time price quote for one US symbol. The market-hours flag is the point — the response never presents a stale price as live.

• Current price, absolute and percent change, session open/high/low, previous close, and an ISO 8601 quote time
• Pairs /quote with /stock/market-status (parallel fan-out) to derive priceIsLive — true only when the US market is open; when closed, current is the prior close, surfaced as such
• Exposes Finnhub's nullable session (pre-market, regular, or post-market) and returned holiday event name without inferring either value
• Market-status failing degrades to marketOpen: null, session: null, and holiday: null rather than tanking the quote
• Unknown US ticker → symbol_not_found; international or paid-only symbol → not_us_or_paid

finnhub_get_company

Full company context for one US symbol in a single call — profile is hollow without the valuation numbers, so this is deliberately one tool over three.

• Profile: name, exchange, industry, country, currency, market cap, shares outstanding, IPO date, website, logo
• Headline fundamentals: P/E (TTM), EPS (TTM), 52-week range, beta, dividend yield, net/gross margin, revenue growth YoY, ROE — every field nullable, surfaced honestly for thinly-covered names rather than zero-filled
• Sector peers from /stock/peers (includes the queried symbol)
• Combines three endpoints under a parallel fan-out; metrics or peers failing degrade to a partial list, profile drives the not-found / forbidden errors

finnhub_get_earnings

Earnings data for one symbol or across the market, selected by mode.

• history (requires symbol): past quarters — actual vs. estimate EPS, absolute surprise, and surprise % (the market-moving signal), newest first
• calendar (uses from / to, defaults to today through +14 days; optional symbol filter): upcoming releases across the market or for one symbol — date, EPS/revenue estimates, expected report time
• limit (1–100, default 50); reports total rows and discloses truncation

finnhub_get_news

Financial news for one company or the broad market, selected by mode.

• company (requires symbol): recent articles over a date range (defaults to the last 7 days) — headline, source, ISO 8601 datetime, summary, URL
• market (uses category): broad headlines by general, forex, crypto, or merger (see the finnhub://news-categories resource)
• limit (1–100, default 15 — news lists run long); articles newest first, with total and truncation disclosure

finnhub_get_recommendations

Analyst recommendation consensus for one US symbol — the view to pair with the live quote and fundamentals.

• Per-month strong-buy / buy / hold / sell / strong-sell counts, newest first (typically 12–24 months of history)
• limit (1–24, default 12 — one year); reports total months and discloses truncation
• Empty result (no analyst coverage) → no_coverage, distinct from an invalid symbol

Resource

The resource is a convenience mirror — its data is fully covered by the category enum 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, and the value is in the freshness, so it's reachable only through the tools.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool and resource definitions — single file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Pluggable auth: none, jwt, oauth
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

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 (unknown US ticker, detected from the all-zero quote / empty profile sentinel) vs. not_us_or_paid (international or paid-only, HTTP 403) — so an agent can tell them apart and recover
• Typed error contracts with recovery hints on every failure, plus the isLikelyUS search heuristic so an agent can prioritize likely free-tier symbols
• Capped lists report their total count and disclose truncation, so an agent knows when more data exists

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.