Financial Hub MCP Server

A TypeScript MCP server for financial data aggregation. Connects any MCP-compatible AI assistant to SEC EDGAR filings, XBRL financial statements, FRED economic indicators, and real-time market data — with built-in XBRL normalization, fact deduplication, computed analytics, stock screening, and rate-limit protection.

Core Concepts

SEC EDGAR

All SEC EDGAR data comes directly from the SEC's free public APIs at data.sec.gov. No API key is required. The server automatically handles:

• XBRL concept resolution — Different companies use different XBRL tags for the same metric. The server normalizes across 20+ financial concepts (e.g., revenue resolves to Revenues, RevenueFromContractWithCustomerExcludingAssessedTax, SalesRevenueNet, and 11 other variants).
• Fact deduplication — Raw XBRL data contains duplicate values from overlapping 10-K/10-Q filings and amendments. The server collapses these to one clean value per fiscal period.
• Rate limiting — SEC enforces 10 requests/second. A token-bucket rate limiter with bounded queuing (max 50 pending, 30s timeout) prevents IP bans.

FRED

FRED (Federal Reserve Economic Data) provides 800,000+ time series from 100+ sources. Requires a free API key from fred.stlouisfed.org. Rate limited to 120 requests/minute (enforced via 2 req/s token bucket). Includes a curated catalog of ~50 essential economic indicators across 9 categories for zero-API-call browsing.

Finnhub Market Data

Real-time stock quotes, company profiles, market news, insider transactions, and financial metrics via the Finnhub API. Free tier provides 30 API calls/second with no credit card required. The server rate-limits to 25 req/s to stay safely under the threshold. Quotes are never cached (stale prices are worse than no cache), while profiles (24h), news (5min), and financial metrics (1h) use appropriate TTLs.

Caching

In-memory LRU cache with TTL expiry reduces redundant API calls:

Eviction is LRU — frequently accessed entries are promoted on read, so the least recently used entry is evicted when capacity is full. Expired entries are proactively swept on every write.

API

Tools

• search_companies

  • Search SEC-registered companies by name or ticker
  • Input: query (string)
  • Returns matching company names, tickers, and CIK numbers

• get_company_filings

  • Get recent SEC filings for a company
  • Inputs:
    • cik (string): SEC's unique company identifier
    • formType (string, optional): Filter by form type (10-K, 10-Q, 8-K, DEF 14A)
  • Returns filing metadata: form type, dates, document links

• get_financial_metric

  • Get deduplicated historical values of a financial metric with trend analysis
  • Inputs:
    • cik (string): Company CIK number
    • concept (string): Friendly name or raw XBRL tag
    • taxonomy (string, optional): XBRL taxonomy (default: us-gaap)
    • annualOnly (boolean, optional): Return only annual data points
  • Accepts friendly names: 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
  • Also accepts raw XBRL tags: Revenues, NetIncomeLoss, Assets, etc.
  • Returns deduplicated values (one per fiscal period), YoY growth rates, and trend direction

• get_financial_summary

  • Get a comprehensive financial snapshot with computed ratios
  • Input: cik (string)
  • Returns latest metrics: revenue, net income, assets, liabilities, equity, cash, debt, EPS, operating cash flow, free cash flow
  • Computed ratios: profit margin, debt-to-equity, current ratio, ROE, ROA
  • All values deduplicated from the most recent annual filing

• get_company_facts_summary

  • Get a compact index of all available XBRL data for a company
  • Inputs:
    • cik (string): Company CIK number
    • limit (number, optional): Max concepts to return (default 40, max 100)
  • Returns concept names, latest values, and data point counts — not the full time series
  • Use this to discover what data is available before drilling into specific metrics

• analyze_financials

  • Deep financial analysis with computed ratios, growth metrics, and health scoring
  • Input: cik (string)
  • Returns:
    • Financial ratios: profit margin, gross margin, operating margin, ROE, ROA, debt-to-equity, current ratio
    • Growth analysis: YoY rates, 3-year and 5-year CAGR, trend detection
    • Composite health grade (A-F) with explanatory factors
  • Uses Promise.allSettled internally — individual metric failures don't crash the analysis

• compare_companies

  • Side-by-side financial comparison of 2-5 companies
  • Input: ciks (string[], 2-5 CIK numbers)
  • Compares revenue, income, assets, cash, EPS, free cash flow, ratios, and health scores
  • Identifies winners by revenue, profitability, growth, and overall health
  • Individual company failures are isolated — partial comparisons still return

• search_filings

  • Full-text search across all SEC EDGAR filings with pagination
  • Inputs:
    • query (string): Search terms
    • forms (string, optional): Comma-separated form types
    • startDate (string, optional): YYYY-MM-DD
    • endDate (string, optional): YYYY-MM-DD
    • limit (number, optional): Results per page (default 20, max 50)
    • offset (number, optional): Skip N results for pagination
  • Returns results array + total hit count for pagination
  • Searches the full text of any filing since 2001

• screen_stocks

  • Screen SEC-registered companies by exchange, industry, name, and financial health
  • Inputs:
    • exchange (string, optional): Filter by exchange (e.g. NYSE, Nasdaq)
    • industry (string, optional): SIC industry group (technology, finance, healthcare, energy, manufacturing, retail, transportation, utilities, services, public_admin)
    • nameContains (string, optional): Case-insensitive substring match on company name
    • minHealthScore (number, optional): Minimum health grade (0-100) from financial analysis
    • limit (number, optional): Max results (default 20, max 50)
  • Two-phase screening: instant client-side filtering on 10,000+ companies, then optional deep filtering via SEC API for industry and health metrics

• get_corporate_events

  • Get recent 8-K corporate events with significance classification
  • Inputs:
    • cik (string): Company CIK number
    • significance (string, optional): Filter by high, medium, or low significance
    • limit (number, optional): Max events (default 15, max 50)
  • Classifies 25 SEC 8-K item numbers into human-readable categories with significance levels
  • High significance: CEO changes, M&A, bankruptcy, material agreements, auditor changes
  • Medium: earnings releases, departures, asset sales, amendments
  • Uses existing submissions data — zero additional API calls

• search_economic_data

  • Search the FRED database for economic data series
  • Input: query (string)
  • Returns series IDs, titles, frequencies, and units
  • Use returned series IDs with get_economic_data

• get_economic_data

  • Get time series observations for a FRED economic data series
  • Inputs:
    • seriesId (string): FRED series ID
    • startDate (string, optional): YYYY-MM-DD
    • endDate (string, optional): YYYY-MM-DD
  • Common series: GDP, CPIAUCSL (CPI), UNRATE (unemployment), FEDFUNDS, DGS10 (10-year treasury), SP500, MORTGAGE30US

• get_stock_quote

  • Get a real-time stock price quote from Finnhub
  • Input: symbol (string): Stock ticker (e.g. AAPL, MSFT, GOOGL)
  • Returns current price, daily change, percent change, day high/low, open, and previous close
  • Live data — never cached

• get_market_news

  • Get latest financial news headlines
  • Inputs:
    • symbol (string, optional): Stock ticker for company-specific news. Omit for general market news
    • category (string, optional): general, forex, crypto, merger (only for general news)
  • Returns up to 20 articles with headline, summary, source, URL, and datetime

• get_insider_transactions

  • Get recent insider trading activity for a company
  • Input: symbol (string): Stock ticker (e.g. AAPL, TSLA)
  • Returns insider names, share counts, transaction dates, prices, and buy/sell codes
  • Transaction codes: P = Purchase, S = Sale, M = Option Exercise, A = Grant/Award, G = Gift, F = Tax withholding

• get_company_overview

  • Get a comprehensive company overview combining profile, market metrics, and peers
  • Input: symbol (string): Stock ticker (e.g. AAPL, MSFT)
  • Returns name, exchange, industry, market cap, PE ratio, beta, 52-week range, EPS, dividend yield, and peer tickers
  • Merges data from 4 parallel Finnhub API calls (profile, financials, peers, quote)

Resources

• sec://company/{ticker}
  • Company profile with SEC metadata and recent filings
  • Includes: name, CIK, tickers, exchanges, SIC code, fiscal year end, and the 10 most recent filings
  • Browsable from any MCP client that supports resources