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": "your-email@example.com",
        "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": "your-email@example.com",
        "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:

Rate-limited fetch — Token bucket ensures SEC's 10 req/s limit is never exceeded. Queue rejects after 50 pending requests or 30s wait.
Caching — Company facts cached for 1 hour, max 15 entries to avoid OOM on large payloads.
Concept resolution — Friendly names like revenue are mapped to all known XBRL tag variants across the us-gaap taxonomy.
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.
Analysis — Growth rates, CAGR, financial ratios, and health scores are computed from clean data.
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

Keywords

mcp

model-context-protocol

FAQs

What is financial-hub-mcp?

Is financial-hub-mcp popular?

Is financial-hub-mcp well maintained?

Package last updated on 17 Apr 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

financial-hub-mcp