Skip to main content
Glama
Financial Hub MCP Server

Financial Hub MCP Server

by ykshah1309

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.

Related MCP server: Financial News and Notes MCP Server

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:

  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

Available Tools

16 tools
analyze_financialsAnalyze Company FinancialsA
Read-onlyIdempotent

Deep financial analysis with computed ratios, growth metrics, and health scoring. Returns profit margins, ROE, ROA, debt-to-equity, current ratio, revenue/income/EPS growth with CAGR, trend detection, and a composite health grade (A-F). This goes beyond raw data — it interprets the numbers.

Inputs: cik (required).

compare_companiesCompare CompaniesA
Read-onlyIdempotent

Side-by-side financial comparison of 2-5 companies with normalized metrics. Compares revenue, income, assets, cash, ratios, and health scores. Identifies the winner in each category. All data is deduplicated and from annual filings.

Inputs: ciks (required).

get_company_facts_summaryGet Company Facts SummaryA
Read-onlyIdempotent

Get a compact index of all available XBRL financial data for a company. Returns concept names, latest values, and data point counts — NOT the full time series. Use this to discover what data is available, then use get_financial_metric for details.

Inputs: cik (required), limit.

get_company_filingsGet Company FilingsA
Read-onlyIdempotent

Get recent SEC filings for a company by CIK number. Returns filing metadata including form type, filing date, and document links. Optionally filter by form type (e.g. 10-K, 10-Q, 8-K, DEF 14A).

Inputs: cik (required), formType.

get_company_overviewGet Company OverviewA
Read-onlyIdempotent

Get a comprehensive company overview combining profile, market metrics, and peer companies. Returns name, exchange, industry, market cap, PE ratio, beta, 52-week range, EPS, dividend yield, and peer tickers. This is the 'market overlay' that complements SEC fundamental data. Requires FINNHUB_API_KEY environment variable.

Inputs: symbol (required).

get_corporate_eventsGet Corporate EventsA
Read-onlyIdempotent

Get recent 8-K corporate events for a company, classified by event type and significance. Covers M&A, earnings announcements, leadership changes, material agreements, cybersecurity incidents, delisting notices, auditor changes, shareholder votes, and more. Each event includes the SEC item number, human-readable label, category, and significance level (high/medium/low).

Inputs: cik (required), limit, significance.

get_economic_dataGet Economic DataA
Read-onlyIdempotent

Get time series observations for a FRED economic data series. Returns recent data points with dates and values. Common series: GDP (Gross Domestic Product), CPIAUCSL (CPI), UNRATE (Unemployment Rate), FEDFUNDS (Fed Funds Rate), DGS10 (10-Year Treasury), SP500 (S&P 500), MORTGAGE30US (30-Year Mortgage Rate).

Inputs: seriesId (required), endDate, startDate.

get_financial_metricGet Financial MetricA
Read-onlyIdempotent

Get deduplicated historical values of a financial metric for a company. Automatically resolves concept aliases — you can use friendly names like 'revenue', 'net_income', 'eps', 'cash', 'total_assets' or raw XBRL tags. Returns clean, one-per-period values with trend analysis. Available concepts: revenue, net_income, gross_profit, operating_income, eps, total_assets, total_liabilities, stockholders_equity, cash, long_term_debt, operating_cash_flow, capex, shares_outstanding.

Inputs: cik (required), concept (required), taxonomy, annualOnly.

get_financial_summaryGet Financial SummaryA
Read-onlyIdempotent

Get a comprehensive financial snapshot with computed ratios. Returns latest revenue, net income, assets, liabilities, equity, cash, debt, EPS — plus profit margin, debt-to-equity, current ratio, and ROE. All values are deduplicated and from the most recent annual filing.

Inputs: cik (required).

get_insider_transactionsGet Insider TransactionsA
Read-onlyIdempotent

Get recent insider trading activity for a company. 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. Requires FINNHUB_API_KEY environment variable.

Inputs: symbol (required).

get_market_newsGet Market NewsA
Read-onlyIdempotent

Get latest financial news headlines. By default returns general market news. Provide a symbol to get company-specific news instead. Categories for general news: general, forex, crypto, merger. Requires FINNHUB_API_KEY environment variable.

Inputs: symbol, category.

get_stock_quoteGet Stock QuoteA
Read-onlyIdempotent

Get a real-time stock price quote. Returns current price, daily change, percent change, day high/low, open price, and previous close. Data is live (not cached) from Finnhub. Requires FINNHUB_API_KEY environment variable.

Inputs: symbol (required).

screen_stocksScreen StocksA
Read-onlyIdempotent

Discover SEC-registered companies by exchange, industry, name, or financial health score. Fast filters (exchange, name) search 10,000+ companies instantly. Deep filters (industry, health score) require per-company API calls and are slower. Available industries: agriculture, mining, construction, manufacturing, transportation, wholesale, retail, finance, services, public_admin.

Inputs: limit, exchange, industry, nameContains, +1 more.

search_companiesSearch CompaniesA
Read-onlyIdempotent

Search for SEC-registered companies by name or ticker symbol. Returns matching company names, tickers, and CIK numbers. Use the CIK for subsequent filing and financial data lookups.

Inputs: query (required).

search_economic_dataSearch Economic DataA
Read-onlyIdempotent

Search the FRED database for economic data series. FRED contains over 800,000 time series from 100+ sources — GDP, inflation, unemployment, interest rates, housing, and more. Returns series IDs that can be used with get_economic_data.

Inputs: query (required).

search_filingsSearch SEC FilingsA
Read-onlyIdempotent

Full-text search across all SEC EDGAR filings. Search for keywords in filing documents, optionally filtered by form type and date range. Supports pagination — use offset to fetch subsequent pages.

Inputs: query (required), forms, limit, offset, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 16 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, but there is some overlap between get_financial_summary, analyze_financials, and get_company_overview, all of which provide financial snapshots. Additionally, search_companies and screen_stocks both serve company discovery, though with different filters and use cases. Descriptions help differentiate them.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with underscores, using 'search_', 'get_', 'analyze_', 'compare_', and 'screen_' as prefixes. No mixed conventions or inconsistent styles are present.

    Tool Count4/5

    The server offers 16 tools covering SEC filings, financial metrics, market data, news, and economic data. This is slightly above the typical 15-tool threshold for a well-scoped set, but each tool has a distinct role and the breadth is justified by the comprehensive 'financial hub' purpose.

    Completeness4/5

    The tool surface covers company discovery, filing retrieval, financial metrics and analysis, market data, news, insider transactions, and economic data. Minor gaps include the lack of a single tool to return full standard financial statements (e.g., income statement or balance sheet), but individual metrics are accessible via get_financial_metric.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      D
      maintenance
      A TypeScript-based MCP server that fetches real-time stock market data and company financial information through the Alpha Vantage API.
      4
      6
      -
    • A
      license
      D
      quality
      A
      maintenance
      A TypeScript-based MCP server that enables users to query financial news, stock data, and index information while managing text notes with creation and summarization capabilities.
      5
      90 npm
      871
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      MCP server for accessing SEC EDGAR filings. Connects AI assistants to company filings, financial statements, and insider trading data with exact numeric precision.
      21
      849 PyPI
      387
      AGPL 3.0