Financial Hub MCP Server

A TypeScript MCP server for financial data aggregation. Connects any MCP-compatible AI assistant to SEC EDGAR filings, structured XBRL financial statements, and FRED economic indicators — with built-in XBRL normalization, fact deduplication, computed analytics, 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).

Caching

In-memory TTL cache reduces redundant API calls:

| Cache | TTL | Max Entries | Payload Size | |-------|-----|-------------|-------------| | Company facts | 1 hour | 15 | 20-50 MB each | | Company submissions | 1 hour | 30 | ~50 KB each | | FRED series metadata | 6 hours | 100 | ~1 KB each | | FRED observations | 1 hour | 50 | ~5 KB each |

Entries are proactively swept on every write to prevent memory buildup from lazy-only deletion.

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

... View full README on GitHub