FinMCP

An MCP (Model Context Protocol) server exposing Indian-market (NSE/BSE) fundamental analysis as tools for LLM clients like Claude Code / Claude Desktop. Full target roadmap: ROADMAP.md.

Tools

Tool	Description
ping	Health check.
search_ticker	Find the NSE/BSE ticker for a company by name -- call this first if you don't already have the exact symbol. Handles two real gotchas: demerged companies can have multiple current tickers (e.g. Tata Motors), and renamed companies return zero matches under their old name (e.g. Zomato -> Eternal Limited).
get_company_news	Recent news headlines/summaries for a company. Yahoo's per-ticker news stream is loosely sector/theme-tagged rather than a strict per-company filter -- expect some broader industry/competitor coverage, and occasionally an outright unrelated story, mixed in with company-specific news. Each article carries a mentions_company flag (a rough, mechanical relevance signal) rather than silently filtering anything out.
get_company_profile	Company profile: sector, industry, market cap, country, exchange, description.
get_income_statement	Revenue, gross profit, operating income, EBIT, EBITDA, net income, EPS per fiscal period (annual/quarterly).
get_balance_sheet	Assets, liabilities, equity, debt, working-capital line items per fiscal period.
get_cash_flow_statement	Operating cash flow, capex, free cash flow, financing cash flow, dividends paid per fiscal period.
get_dividend_history	Dividend and stock-split history. An empty dividend list is a legitimate result, not an error.
get_stock_price_history	OHLCV bars (period: 1mo-max, interval: 1d/1wk/1mo). Capped at 500 bars.
calculate_financial_ratios	P/E, P/B, EV/EBITDA, EV/Sales, ROCE, ROE, ROA, current ratio, debt/equity, interest coverage, asset turnover, margins, FCF/earnings yield -- ratios Yahoo leaves null are computed by hand from the statements.
calculate_growth_metrics	Revenue/net income/EPS/FCF CAGR over the available annual history (~4Y).
analyze_margin_trends	Gross/operating/net margin across the available annual history + first-vs-latest delta.
analyze_cash_flow_quality	Cash conversion (CFO/FCF vs net income) and receivables/inventory-outpacing-revenue flags.
peer_valuation	Side-by-side multiples + a transparent peer-relative attractiveness score against explicit peer tickers you supply (Yahoo has no peer-discovery endpoint for Indian equities).
historical_valuation	Current P/E vs the company's own historical annual P/E, with a percentile rank.
reverse_dcf	What growth rate the current share price already implies (two-stage DCF solved by bisection), vs what the company has historically achieved.
dcf_valuation	Forward DCF: intrinsic value per share and margin of safety given growth/discount-rate assumptions (growth defaults to historical revenue CAGR). Same math as reverse_dcf, run the other direction -- cross-check the two.
financial_health_score	Transparent 0-100 rubric across profitability, growth, balance sheet, cash flow, and valuation.
detect_earnings_quality	Flags + 0-100 score: profit-up/cash-flow-down divergence, receivables/inventory outpacing revenue, CFO vs net income, FCF consistency, other-income reliance.
detect_accounting_red_flags	Sudden margin swings, debt spikes, goodwill/intangible growth outpacing total assets, repeated exceptional items. Does not cover related-party transactions or depreciation patterns (no Yahoo data / no reliable basis).
analyze_capital_allocation	Per fiscal year: free cash flow split across dividends, buybacks, acquisitions, net debt repayment.
analyze_management_quality	Multi-year ROCE trend, share-count trend (dilution vs buybacks), dividend consistency, capital allocation. Deliberately excludes promoter shareholding (Yahoo doesn't have the SEBI promoter/FII/DII/public breakdown).
compare_companies	Profile + key ratios + growth + health score, side by side, for up to 5 symbols.
analyze_company	The complete fundamental-analysis pipeline for one symbol in a single call -- composes every tool above.
find_undervalued_companies	Screens an explicit candidate list (max 15; Yahoo has no NIFTY-500-style universe endpoint) for cheap-vs-own-history + reverse-DCF growth cushion, ranked best-first.
find_high_quality_companies	Screens an explicit candidate list, ranked by health score with earnings-quality/red-flag tiebreakers.
generate_investment_memo	Structured research memo (profitability, growth, cash flow, management, valuation, risks, bull/bear case) composed from analyze_company's output. Bull/bear bullets are mechanically derived from computed flags, not fabricated research; no "Catalysts" section (needs analyst/news data this server doesn't have).
bankruptcy_risk_score	Altman Z''-score (EM/non-manufacturing variant) with SAFE/GREY/DISTRESS zone. Entirely book-value/statement-derived, so unlike most valuation tools here it's unaffected by the currency-mismatch issue. Does not include Ohlson's O-score (needs a US GNP price-level deflator with no Indian equivalent).

All tools cover NSE/BSE-listed Indian equities only. A bare symbol (e.g. "RELIANCE") is normalized to NSE (.NS) by default; pass an explicit .BO suffix for BSE. Several tools carry a currency_mismatch_warning field -- Yahoo reports some Indian large caps' (e.g. INFY, HCLTECH) financial statements in USD while market data is in INR, which silently corrupts any ratio mixing the two; this is detected and surfaced rather than hidden.

Requirements

• Python 3.12+
• uv for environment, dependency, and build management

Setup

uv sync

This creates .venv/ and installs all dependencies, pinned via uv.lock.

Running

# Run the server directly over stdio (what MCP clients expect)
uv run finmcp

# Or via the module entrypoint
uv run python -m finmcp

# Launch the MCP Inspector to poke at tools interactively
uv run mcp dev src/finmcp/server.py

Using with Claude Code / Claude Desktop

Add to your MCP client config:

{
  "mcpServers": {
    "fin-mcp": {
      "command": "uv",
      "args": ["--directory", "/home/prem/Documents/FinMCP-Fundamentals", "run", "finmcp"]
    }
  }
}

Or register with Claude Code directly:

claude mcp add fin-mcp --scope user -- uv --directory /home/prem/Documents/FinMCP-Fundamentals run finmcp

Development

uv run pytest        # run tests
uv run ruff check .  # lint
uv build             # build wheel/sdist into dist/

Docker (Stage 3 stub)

docker build -t finmcp .
docker run -i finmcp

The image builds and runs the stdio server today; full Docker MCP Toolkit catalog integration (metadata, tool listing) is deferred to Stage 3, once the real Yahoo Finance tools exist.

Disclaimer

Yahoo Finance data is accessed via the unofficial yfinance library, which is not affiliated with, endorsed by, or vetted by Yahoo, Inc. Intended for research/educational use.

License

MIT