{
  "markdown": "# Financial Hub MCP Server\n\nA 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.\n\n## Core Concepts\n\n### SEC EDGAR\n\nAll 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:\n\n- **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).\n- **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.\n- **Rate limiting** — SEC enforces 10 requests/second. A token-bucket rate limiter with bounded queuing (max 50 pending, 30s timeout) prevents IP bans.\n\n### FRED\n\nFRED (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.\n\n### Finnhub Market Data\n\nReal-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.\n\n### Caching\n\nIn-memory LRU cache with TTL expiry reduces redundant API calls:\n\n| Cache | TTL | Max Entries | Payload Size |\n|-------|-----|-------------|-------------|\n| Company facts | 1 hour | 10 | 20-50 MB each |\n| Company submissions | 1 hour | 30 | ~50 KB each |\n| Company tickers | 24 hours | 1 | ~3 MB |\n| FRED series metadata | 6 hours | 100 | ~1 KB each |\n| FRED observations | 1 hour | 50 | ~5 KB each |\n| Market profiles | 24 hours | 50 | ~1 KB each |\n| Market news | 5 minutes | 10 | ~5 KB each |\n| Insider transactions | 1 hour | 30 | ~3 KB each |\n| Basic financials | 1 hour | 30 | ~2 KB each |\n\nEviction 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.\n\n## API\n\n### Tools\n\n- **search_companies**\n  - Search SEC-registered companies by name or ticker\n  - Input: `query` (string)\n  - Returns matching company names, tickers, and CIK numbers\n\n- **get_company_filings**\n  - Get recent SEC filings for a company\n  - Inputs:\n    - `cik` (string): SEC's unique company identifier\n    - `formType` (string, optional): Filter by form type (10-K, 10-Q, 8-K, DEF 14A)\n  - Returns filing metadata: form type, dates, document links\n\n- **get_financial_metric**\n  - Get deduplicated historical values of a financial metric with trend analysis\n  - Inputs:\n    - `cik` (string): Company CIK number\n    - `concept` (string): Friendly name or raw XBRL tag\n    - `taxonomy` (string, optional): XBRL taxonomy (default: `us-gaap`)\n    - `annualOnly` (boolean, optional): Return only annual data points\n  - 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`\n  - Also accepts raw XBRL tags: `Revenues`, `NetIncomeLoss`, `Assets`, etc.\n  - Returns deduplicated values (one per fiscal period), YoY growth rates, and trend direction\n\n- **get_financial_summary**\n  - Get a comprehensive financial snapshot with computed ratios\n  - Input: `cik` (string)\n  - Returns latest metrics: revenue, net income, assets, liabilities, equity, cash, debt, EPS, operating cash flow, free cash flow\n  - Computed ratios: profit margin, debt-to-equity, current ratio, ROE, ROA\n  - All values deduplicated from the most recent annual filing\n\n- **get_company_facts_summary**\n  - Get a compact index of all available XBRL data for a company\n  - Inputs:\n    - `cik` (string): Company CIK number\n    - `limit` (number, optional): Max concepts to return (default 40, max 100)\n  - Returns concept names, latest values, and data point counts — not the full time series\n  - Use this to discover what data is available before drilling into specific metrics\n\n- **analyze_financials**\n  - Deep financial analysis with computed ratios, growth metrics, and health scoring\n  - Input: `cik` (string)\n  - Returns:\n    - Financial ratios: profit margin, gross margin, operating margin, ROE, ROA, debt-to-equity, current ratio\n    - Growth analysis: YoY rates, 3-year and 5-year CAGR, trend detection\n    - Composite health grade (A-F) with explanatory factors\n  - Uses `Promise.allSettled` internally — individual metric failures don't crash the analysis\n\n- **compare_companies**\n  - Side-by-side financial comparison of 2-5 companies\n  - Input: `ciks` (string[], 2-5 CIK numbers)\n  - Compares revenue, income, assets, cash, EPS, free cash flow, ratios, and health scores\n  - Identifies winners by revenue, profitability, growth, and overall health\n  - Individual company failures are isolated — partial comparisons still return\n\n- **search_filings**\n  - Full-text search across all SEC EDGAR filings with pagination\n  - Inputs:\n    - `query` (string): Search terms\n    - `forms` (string, optional): Comma-separated form types\n    - `startDate` (string, optional): YYYY-MM-DD\n    - `endDate` (string, optional): YYYY-MM-DD\n    - `limit` (number, optional): Results per page (default 20, max 50)\n    - `offset` (number, optional): Skip N results for pagination\n  - Returns results array + total hit count for pagination\n  - Searches the full text of any filing since 2001\n\n- **screen_stocks**\n  - Screen SEC-registered companies by exchange, industry, name, and financial health\n  - Inputs:\n    - `exchange` (string, optional): Filter by exchange (e.g. NYSE, Nasdaq)\n    - `industry` (string, optional): SIC industry group (technology, finance, healthcare, energy, manufacturing, retail, transportation, utilities, services, public_admin)\n    - `nameContains` (string, optional): Case-insensitive substring match on company name\n    - `minHealthScore` (number, optional): Minimum health grade (0-100) from financial analysis\n    - `limit` (number, optional): Max results (default 20, max 50)\n  - Two-phase screening: instant client-side filtering on 10,000+ companies, then optional deep filtering via SEC API for industry and health metrics\n\n- **get_corporate_events**\n  - Get recent 8-K corporate events with significance classification\n  - Inputs:\n    - `cik` (string): Company CIK number\n    - `significance` (string, optional): Filter by `high`, `medium`, or `low` significance\n    - `limit` (number, optional): Max events (default 15, max 50)\n  - Classifies 25 SEC 8-K item numbers into human-readable categories with significance levels\n  - High significance: CEO changes, M&A, bankruptcy, material agreements, auditor changes\n  - Medium: earnings releases, departures, asset sales, amendments\n  - Uses existing submissions data — zero additional API calls\n\n- **search_economic_data**\n  - Search the FRED database for economic data series\n  - Input: `query` (string)\n  - Returns series IDs, titles, frequencies, and units\n  - Use returned series IDs with `get_economic_data`\n\n- **get_economic_data**\n  - Get time series observations for a FRED economic data series\n  - Inputs:\n    - `seriesId` (string): FRED series ID\n    - `startDate` (string, optional): YYYY-MM-DD\n    - `endDate` (string, optional): YYYY-MM-DD\n  - Common series: `GDP`, `CPIAUCSL` (CPI), `UNRATE` (unemployment), `FEDFUNDS`, `DGS10` (10-year treasury), `SP500`, `MORTGAGE30US`\n\n- **get_stock_quote**\n  - Get a real-time stock price quote from Finnhub\n  - Input: `symbol` (string): Stock ticker (e.g. AAPL, MSFT, GOOGL)\n  - Returns current price, daily change, percent change, day high/low, open, and previous close\n  - Live data — never cached\n\n- **get_market_news**\n  - Get latest financial news headlines\n  - Inputs:\n    - `symbol` (string, optional): Stock ticker for company-specific news. Omit for general market news\n    - `category` (string, optional): `general`, `forex`, `crypto`, `merger` (only for general news)\n  - Returns up to 20 articles with headline, summary, source, URL, and datetime\n\n- **get_insider_transactions**\n  - Get recent insider trading activity for a company\n  - Input: `symbol` (string): Stock ticker (e.g. AAPL, TSLA)\n  - Returns insider names, share counts, transaction dates, prices, and buy/sell codes\n  - Transaction codes: P = Purchase, S = Sale, M = Option Exercise, A = Grant/Award, G = Gift, F = Tax withholding\n\n- **get_company_overview**\n  - Get a comprehensive company overview combining profile, market metrics, and peers\n  - Input: `symbol` (string): Stock ticker (e.g. AAPL, MSFT)\n  - Returns name, exchange, industry, market cap, PE ratio, beta, 52-week range, EPS, dividend yield, and peer tickers\n  - Merges data from 4 parallel Finnhub API calls (profile, financials, peers, quote)\n\n### Resources\n\n- **sec://company/{ticker}**\n  - Company profile with SEC metadata and recent filings\n  - Includes: name, CIK, tickers, exchanges, SIC code, fiscal year end, and the 10 most recent filings\n  - Browsable from any MCP client that supports resources\n\n- **fred://catalog/{category}**\n  - Browse curated FRED economic indicators by category\n  - Categories: gdp, labor, inflation, rates, housing, markets, money, trade, consumer\n  - Returns series IDs, titles, frequencies, and descriptions — zero API calls\n\n- **fred://indicator/{seriesId}**\n  - FRED indicator detail with latest observations\n  - Returns series metadata from the catalog plus the 10 most recent data points\n  - Use this to inspect a specific indicator before pulling full time series\n\n### Prompts\n\n- **financial_analysis**\n  - Guided company financial health analysis\n  - Input: `ticker` (string)\n  - Walks through revenue trends, profitability, balance sheet health, and risk assessment\n\n- **peer_comparison**\n  - Side-by-side comparison of two companies\n  - Input: `ticker1` (string), `ticker2` (string)\n\n- **economic_overview**\n  - Current US economic conditions dashboard\n  - No input required\n  - Pulls GDP, unemployment, CPI, fed funds rate, treasury yields, and mortgage rates\n\n### Tool Annotations\n\nAll tools set [MCP ToolAnnotations](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#toolannotations) for safe agent composition:\n\n| Hint | Value | Reason |\n|------|-------|--------|\n| `readOnlyHint` | `true` | All tools are read-only — no data is modified |\n| `destructiveHint` | `false` | No data destruction |\n| `idempotentHint` | `true` | Same inputs produce same outputs |\n| `openWorldHint` | `true` | All tools make external API calls |\n\n### Error Handling\n\nAll tools return MCP-compliant error envelopes with `isError: true` on failure:\n\n```json\n{\n  \"content\": [{ \"type\": \"text\", \"text\": \"SEC EDGAR request failed: 404 Not Found\" }],\n  \"isError\": true\n}\n```\n\nThis 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.\n\n## Usage with Claude Desktop\n\nAdd this to your `claude_desktop_config.json`:\n\n### NPX\n\n```json\n{\n  \"mcpServers\": {\n    \"financial-hub\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"financial-hub-mcp\"],\n      \"env\": {\n        \"FRED_API_KEY\": \"your-free-api-key\",\n        \"SEC_USER_AGENT_EMAIL\": \"your-email@example.com\",\n        \"FINNHUB_API_KEY\": \"your-free-api-key\"\n      }\n    }\n  }\n}\n```\n\n## Usage with VS Code\n\nFor 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:\n\n### NPX\n\n```json\n{\n  \"servers\": {\n    \"financial-hub\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"financial-hub-mcp\"],\n      \"env\": {\n        \"FRED_API_KEY\": \"your-free-api-key\",\n        \"SEC_USER_AGENT_EMAIL\": \"your-email@example.com\",\n        \"FINNHUB_API_KEY\": \"your-free-api-key\"\n      }\n    }\n  }\n}\n```\n\n> 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).\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `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. |\n| `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. |\n| `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. |\n\n## Architecture\n\n```\nsrc/\n├── index.ts              # Entry point — startup validation, MCP server init\n├── rate-limiter.ts       # Token-bucket rate limiter with bounded queue + timeout\n├── cache.ts              # In-memory TTL cache with proactive eviction\n├── edgar/\n│   ├── client.ts         # SEC EDGAR HTTP client (rate-limited, cached)\n│   ├── tools.ts          # MCP tool registrations (12 tools, isError envelopes)\n│   ├── resources.ts      # MCP resource templates (company profiles)\n│   ├── xbrl.ts           # XBRL fact deduplication, growth, trend detection\n│   ├── concepts.ts       # Concept alias normalization (20+ financial concepts)\n│   ├── analytics.ts      # Computed ratios, health scoring, company comparison\n│   ├── events.ts         # 8-K corporate event classification (25 item types)\n│   └── screening.ts      # Stock screening by exchange, industry, health score\n├── fred/\n│   ├── client.ts         # FRED HTTP client (rate-limited, cached)\n│   ├── tools.ts          # FRED MCP tool registrations\n│   ├── catalog.ts        # Curated catalog of ~50 essential FRED indicators\n│   └── resources.ts      # FRED MCP resource templates (catalog + indicators)\n├── market/\n│   ├── client.ts         # Finnhub HTTP client (rate-limited, cached)\n│   └── tools.ts          # Market data MCP tool registrations (4 tools)\n└── prompts.ts            # Financial analysis prompt templates\n```\n\n### Data Pipeline\n\nRaw XBRL data from SEC EDGAR goes through several processing stages:\n\n1. **Rate-limited fetch** — Token bucket ensures SEC's 10 req/s limit is never exceeded. Queue rejects after 50 pending requests or 30s wait.\n2. **Caching** — Company facts cached for 1 hour, max 15 entries to avoid OOM on large payloads.\n3. **Concept resolution** — Friendly names like `revenue` are mapped to all known XBRL tag variants across the us-gaap taxonomy.\n4. **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.\n5. **Analysis** — Growth rates, CAGR, financial ratios, and health scores are computed from clean data.\n6. **Serialization** — Minified JSON output to minimize context window usage.\n\n## Building from Source\n\n```bash\ngit clone https://github.com/ykshah1309/financial-hub-mcp.git\ncd financial-hub-mcp\nnpm install\nnpm run build\n```\n\nRun locally:\n\n```bash\nFRED_API_KEY=your-key SEC_USER_AGENT_EMAIL=your-email FINNHUB_API_KEY=your-key node dist/index.js\n```\n\n## Contributing\n\nPull requests welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development loop, commit style, and PR checklist. By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).\n\n## Security\n\nPlease report security issues privately — see [SECURITY.md](SECURITY.md). Do not file public issues for vulnerabilities or credential leaks.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for release notes.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## Badges\n\n[![MCP Badge](https://lobehub.com/badge/mcp/ykshah1309-financial-hub-mcp)](https://lobehub.com/mcp/ykshah1309-financial-hub-mcp)\n",
  "bytes": 16741,
  "sha": "5936845431dae3b0e330309549d07e2ab47734809a0b66f2b2b3f39ee7323e60",
  "repo_slug": "ykshah1309/financial-hub-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ykshah1309_financial_hub_mcp_a6ecbe18/readme"
}