FinResearch MCP

FinResearch MCP is a production-oriented Model Context Protocol server for SEC EDGAR Company Facts research, financial analysis, valuation, and plot-ready data. It is designed as a transparent foundation for AI-assisted equity research—not as investment advice.

Highlights

• Reusable, rate-limited SEC client with timeouts, transient retries, response validation, and a five-minute in-memory Company Facts cache.
• Normalized annual financial histories for income statement, cash-flow, and balance-sheet metrics.
• Profitability, liquidity, leverage, efficiency, and cash-conversion ratios.
• Assumption-driven CAPM, WACC, DCF, enterprise value, equity value, intrinsic value, and sensitivity analysis tools.
• High-level company analysis, peer comparison, and structured chart data.
• Provider-neutral RAG contracts for future 10-K/10-Q, MD&A, and risk-factor retrieval.

Installation and usage

Requirements: Python 3.12+, uv, and a contact email address for SEC requests.

uv sync
uv run mcp dev main.py

mcp dev main.py launches MCP Inspector. The exported main:mcp object also works with stdio-based MCP clients. Set FINRESEARCH_LOG_LEVEL=DEBUG for diagnostic logs; logs use stderr so MCP stdio remains clean.

Tools

Area	Tools
Existing tools	calculate_cagr, get_sec_company_facts, get_financial_fact
Financial data	get_company_financials, get_financial_ratios
Analysis	analyze_company, get_company_chart_data, compare_companies
Valuation	calculate_capm_cost_of_equity, calculate_wacc_rate, calculate_dcf_valuation, calculate_enterprise_value, calculate_equity_value_from_enterprise_value, calculate_intrinsic_value_per_share, run_dcf_sensitivity_analysis
Version 2 platform	ai_analyze_company, index_sec_filing, search_sec_filing_rag, analyze_portfolio, get_market_snapshot, get_market_price_history, get_dashboard_data, export_company_report_markdown, export_company_report_pdf

get_company_financials covers revenue, revenue history, net income, operating income/EBIT, gross profit, EBITDA when depreciation data is reported, EPS, diluted EPS, operating cash flow, free cash flow, CapEx, cash, debt, current assets/liabilities, total assets/liabilities, equity, and book value. Market capitalization and market-derived enterprise value are explicitly null because SEC Company Facts is not a market-data service.

Data and calculation notes

• Annual duration facts are 10-K records between 330 and 380 days; when a period has multiple filings, the most recently filed observation is used.
• Instant balance-sheet facts use their latest 10-K period end.
• Unreported or non-standard company concepts return null; the server does not fabricate estimates.
• Ratio calculations use reported latest values. ROIC assumes a 21% tax rate where tax expense is not consistently available.
• DCF tools require explicit assumptions and return structured intermediate projections for auditability.

Development

.venv/bin/python -m compileall -q main.py clients models rag tools utils tests
.venv/bin/python -m unittest discover -s tests -v

The tests use mocked HTTP transports and never call SEC EDGAR. See architecture documentation, RAG preparation, and example prompts. See Version 2 platform documentation for filing RAG, market-data limitations, dashboard payloads, portfolios, and report exports.

Folder structure

clients/   SEC API integration
models/    typed financial domain models
tools/     MCP tool groups
utils/     extraction, ratios, valuation, logging, constants
rag/       future filing-retrieval interfaces
tests/     offline unit tests
docs/      architecture and RAG design
examples/  prompts for MCP clients