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

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