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:

| Cache | TTL | Max Entries | Payload Size | |-------|-----|-------------|-------------| | Company facts | 1 hour | 10 | 20-50 MB each | | Company submissions | 1 hour | 30 | ~50 KB each | | Company tickers | 24 hours | 1 | ~3 MB | | FRED series metadata | 6 hours | 100 | ~1 KB each | | FRED observations | 1 hour | 50 | ~5 KB each | | Market profiles | 24 hours | 50 | ~1 KB each | | Market news | 5 minutes | 10 | ~5 KB each | | Insider transactions | 1 hour | 30 | ~3 KB each | | Basic financials | 1 hour | 30 | ~2 KB each |

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

• fred://catalog/{category}

  • Browse curated FRED economic indicators by category
  • Categories: gdp, labor, inflation, rates, housing, markets, money, trade, consumer
  • Returns series IDs, titles, frequencies, and descriptions — zero API calls

• fred://indicator/{seriesId}

  • FRED indicator detail with latest observations
  • Returns series metadata from the catalog plus the 10 most recent data points
  • Use this to inspect a specific indicator before pulling full time series

Prompts

• financial_analysis

  • Guided company financial health analysis
  • Input: ticker (string)
  • Walks through revenue trends, profitability, balance sheet health, and risk assessment

• peer_comparison

  • Side-by-side comparison of two companies
  • Input: ticker1 (string), ticker2 (string)

• economic_overview

  • Current US economic conditions dashboard
  • No input required
  • Pulls GDP, unemployment, CPI, fed funds rate, treasury yields, and mortgage rates

Tool Annotations

All tools set MCP ToolAnnotations for safe agent composition:

| Hint | Value | Reason | |------|-------|--------| | readOnlyHint | true | All tools are read-only — no data is modified | | destructiveHint | false | No data destruction | | idempotentHint | true | Same inputs produce same outputs | | openWorldHint | true | All tools make external API calls |

Error Handling

All tools return MCP-compliant error envelopes with isError: true on failure:

{
  "content": [{ "type": "text", "text": "SEC EDGAR request failed: 404 Not Found" }],
  "isError": true
}

This allows the LLM to receive semantic error messages, correct parameters, and retry — rather than receiving opaque transport-level JSON-RPC errors that break the agent loop.

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

NPX

{
  "mcpServers": {
    "financial-hub": {
      "command": "npx",
      "args": ["-y", "financial-hub-mcp"],
      "env": {
        "FRED_API_KEY": "your-free-api-key",
        "SEC_USER_AGENT_EMAIL": "[email protected]",
        "FINNHUB_API_KEY": "your-free-api-key"
      }
    }
  }
}

Usage with VS Code

For manual installation, add the configuration to your user-level MCP configuration file. Open the Command Palette (Ctrl + Shift + P) and run MCP: Open User Configuration, then add:

NPX

{
  "servers": {
    "financial-hub": {
      "command": "npx",
      "args": ["-y", "financial-hub-mcp"],
      "env": {
        "FRED_API_KEY": "your-free-api-key",
        "SEC_USER_AGENT_EMAIL": "[email protected]",
        "FINNHUB_API_KEY": "your-free-api-key"
      }
    }
  }
}

For more details about MCP configuration in VS Code, see the official VS Code MCP documentation.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | SEC_USER_AGENT_EMAIL | Yes | Your email address for SEC EDGAR API compliance. The server will exit immediately if this is not set — SEC EDGAR bans requests with missing or generic User-Agent headers. | | FRED_API_KEY | For FRED tools | Free 32-character key from fred.stlouisfed.org. The server starts without it but FRED tools will fail at runtime with a clear error message. | | FINNHUB_API_KEY | For market tools | Free API key from finnhub.io. Required for stock quotes, market news, insider transactions, and company overviews. The server starts without it but market tools will fail at runtime. |

Architecture

src/
├── index.ts              # Entry point — startup validation, MCP server init
├── rate-limiter.ts       # Token-bucket rate limiter with bounded queue + timeout
├── cache.ts              # In-memory TTL cache with proactive eviction
├── edgar/
│   ├── client.ts         # SEC EDGAR HTTP client (rate-limited, cached)
│   ├── tools.ts          # MCP tool registrations (12 tools, isError envelopes)
│   ├── resources.ts      # MCP resource templates (company profiles)
│   ├── xbrl.ts           # XBRL fact deduplication, growth, trend detection
│   ├── concepts.ts       # Concept alias normalization (20+ financial concepts)
│   ├── analytics.ts      # Computed ratios, health scoring, company comparison
│   ├── events.ts         # 8-K corporate event classification (25 item types)
│   └── screening.ts      # Stock screening by exchange, industry, health score
├── fred/
│   ├── client.ts         # FRED HTTP client (rate-limited, cached)
│   ├── tools.ts          # FRED MCP tool registrations
│   ├── catalog.ts        # Curated catalog of ~50 essential FRED indicators
│   └── resources.ts      # FRED MCP resource templates (catalog + indicators)
├── market/
│   ├── client.ts         # Finnhub HTTP client (rate-limited, cached)
│   └── tools.ts          # Market data MCP tool registrations (4 tools)
└── prompts.ts            # Financial analysis prompt templates

Data Pipeline

Raw XBRL data from SEC EDGAR goes through several processing stages:

1. Rate-limited fetch — Token bucket ensures SEC's 10 req/s limit is never exceeded. Queue rejects after 50 pending requests or 30s wait.
2. Caching — Company facts cached for 1 hour, max 15 entries to avoid OOM on large payloads.
3. Concept resolution — Friendly names like revenue are mapped to all known XBRL tag variants across the us-gaap taxonomy.
4. Deduplication — Overlapping 10-K/10-Q/amendment values are collapsed to one per fiscal period. Prefers 10-K over 10-Q, latest filing date over earlier.
5. Analysis — Growth rates, CAGR, financial ratios, and health scores are computed from clean data.
6. Serialization — Minified JSON output to minimize context window usage.

Building from Source

git clone https://github.com/ykshah1309/financial-hub-mcp.git
cd financial-hub-mcp
npm install
npm run build

Run locally:

FRED_API_KEY=your-key SEC_USER_AGENT_EMAIL=your-email FINNHUB_API_KEY=your-key node dist/index.js

Contributing

Pull requests welcome. See CONTRIBUTING.md for the development loop, commit style, and PR checklist. By participating you agree to the Code of Conduct.

Security

Please report security issues privately — see SECURITY.md. Do not file public issues for vulnerabilities or credential leaks.

Changelog

See CHANGELOG.md for release notes.

License

MIT — see LICENSE.

Badges