Financial Hub 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

MCP Badge