# financial-hub-mcp [Health: Active] **Category:** 💰 Finance & Fintech **Repository:** https://github.com/ykshah1309/financial-hub-mcp **GitHub Stars:** 1 **npm Downloads (last month):** 269 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/financial-hub-mcp ## Description SEC EDGAR filings, XBRL financials, and FRED economic indicators for MCP clients ## Tools Capabilities this server exposes over MCP: - **query** - **cik** - **formType** - **concept** - **taxonomy** - **us-gaap** - **annualOnly** - **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** - **Revenues** - **NetIncomeLoss** - **Assets** - **limit** - **Promise.allSettled** - **ciks** - **forms** - **startDate** - **endDate** - **offset** - **exchange** - **industry** - **nameContains** - **minHealthScore** - **significance** - **high** - **medium** - **low** - **get_economic_data** - **seriesId** - **GDP** - **CPIAUCSL** - **UNRATE** - **FEDFUNDS** - **DGS10** - **SP500** - **MORTGAGE30US** - **symbol** - **category** - **general** - **forex** - **crypto** - **merger** ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "financial-hub-mcp": { "command": "npx", "args": ["-y","financial-hub-mcp"] } } ``` ## Documentation & README # 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](https://fred.stlouisfed.org/docs/api/api_key.html). 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](https://finnhub.io). 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](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#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: ```json { "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 ```json { "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 ```json { "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](https://code.visualstudio.com/docs/copilot/customization/mcp-servers). ## 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](https://fred.stlouisfed.org/docs/api/api_key.html). 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](https://finnhub.io/register). 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 ```bash git clone https://github.com/ykshah1309/financial-hub-mcp.git cd financial-hub-mcp npm install npm run build ``` Run locally: ```bash 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](https://github.com/ykshah1309/financial-hub-mcp/blob/HEAD/CONTRIBUTING.md) for the development loop, commit style, and PR checklist. By participating you agree to the [Code of Conduct](https://github.com/ykshah1309/financial-hub-mcp/blob/HEAD/CODE_OF_CONDUCT.md). ## Security Please report security issues privately — see [SECURITY.md](https://github.com/ykshah1309/financial-hub-mcp/blob/HEAD/SECURITY.md). Do not file public issues for vulnerabilities or credential leaks. ## Changelog See [CHANGELOG.md](https://github.com/ykshah1309/financial-hub-mcp/blob/HEAD/CHANGELOG.md) for release notes. ## License MIT — see [LICENSE](https://github.com/ykshah1309/financial-hub-mcp/blob/HEAD/LICENSE). ## Badges [![MCP Badge](https://lobehub.com/badge/mcp/ykshah1309-financial-hub-mcp)](https://lobehub.com/mcp/ykshah1309-financial-hub-mcp)