io.github.ykshah1309/financial-hub-mcp
SEC EDGAR filings, XBRL financials, and FRED economic indicators for MCP clients
Ask AI about io.github.ykshah1309/financial-hub-mcp
Powered by Claude Β· Grounded in docs
I know everything about io.github.ykshah1309/financial-hub-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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.,
revenueresolves toRevenues,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 identifierformType(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 numberconcept(string): Friendly name or raw XBRL tagtaxonomy(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 numberlimit(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.allSettledinternally β 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 termsforms(string, optional): Comma-separated form typesstartDate(string, optional): YYYY-MM-DDendDate(string, optional): YYYY-MM-DDlimit(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 nameminHealthScore(number, optional): Minimum health grade (0-100) from financial analysislimit(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 numbersignificance(string, optional): Filter byhigh,medium, orlowsignificancelimit(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 IDstartDate(string, optional): YYYY-MM-DDendDate(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 newscategory(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
revenueare 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.
