# 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](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`](https://docs.astral.sh/uv/) for environment, dependency, and build management

## Setup

```bash
uv sync
```

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

## Running

```bash
# 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:

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

Or register with Claude Code directly:

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

## Development

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

## Docker (Stage 3 stub)

```bash
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`](https://github.com/ranaroussi/yfinance)
library, which is not affiliated with, endorsed by, or vetted by Yahoo, Inc.
Intended for research/educational use.

## License

[MIT](LICENSE)