# screener-mcp-pro

An [MCP](https://modelcontextprotocol.io) server that gives an LLM (e.g. Claude) rich, structured data on Indian-listed
companies: fundamentals and financial statements scraped from [Screener.in](https://www.screener.in), plus
price-based technical indicators from Yahoo Finance. Built for deep, one-stock-at-a-time research — ratios, multi-year
financials, shareholding trends, peer comparisons, annual reports/credit ratings/concall links, and SMA/RSI/ATR — in a
single tool call.

Not affiliated with screener.in or Yahoo Finance.

## Tools

| Tool | What it returns | Login needed? |
|---|---|---|
| `screener_get_full_company_snapshot` | Everything below, in one call | No |
| `screener_get_company_overview` | P/E, book value, ROE, ROCE, market cap, dividend yield, About, pros/cons | No |
| `screener_get_quarterly_results` | Quarterly sales/profit table | No |
| `screener_get_profit_loss` | Multi-year P&L with compounded growth | No |
| `screener_get_balance_sheet` | Multi-year balance sheet | No |
| `screener_get_cash_flow` | Multi-year cash flow, incl. free cash flow | No |
| `screener_get_shareholding_pattern` | Promoter/FII/DII/govt/public % trend | No |
| `screener_get_peer_comparison` | Peer CMP/P/E/market cap/ROCE table | No |
| `screener_get_documents` | Announcements, annual reports, credit ratings, concall links | No |
| `screener_get_company_insights` | Headcount, $100M+ clients, revenue mix by geography/vertical, TCV, attrition | **Yes** (see below) |
| `screener_get_technical_indicators` | SMA20/50/200, RSI14, ATR14, 52w high/low (Yahoo Finance) | No |
| `screener_login_status` | Diagnostic: are credentials configured, did login succeed | N/A |

## Install

```bash
claude mcp add screener-pro -- uvx --from git+https://github.com/vidyasagardivi9/screener-mcp-pro- screener-mcp-pro
```

(Registered as `screener-pro` so it doesn't collide with any other `screener` MCP server you may already have.)

### Optional: enable the Insights tool

Every tool above except `screener_get_company_insights` works with zero configuration — screener.in serves company
pages, financial statements, peer data, and documents publicly. The **Insights** section (headcount, client counts,
revenue mix, etc.) is different: screener.in only sends those numbers to logged-in sessions. If you want that tool to
return real values instead of just the metric names, register with your own credentials:

```bash
claude mcp add screener-pro -e SCREENER_USERNAME=you@example.com -e SCREENER_PASSWORD=your_password \
  -- uvx --from git+https://github.com/vidyasagardivi9/screener-mcp-pro- screener-mcp-pro
```

Credentials are read only from these environment variables, kept in an in-memory cookie jar for the process's
lifetime, and never written to disk or logged. See `.env.example` for all supported variables.

## Known limitations

- **No company-search tool.** screener.in's `robots.txt` disallows crawling its `?q=` search endpoint, so every tool
  takes an explicit `symbol` (the screener.in slug, normally identical to the NSE trading symbol — e.g. `TCS`,
  `INFY`, `RELIANCE`). Resolve the ticker yourself or let the calling LLM infer it from general knowledge.
- **Scraping-based, not an official API.** Parsers degrade gracefully (partial results plus a `warnings` list) if
  screener.in changes its page structure, but they can still break. `tests/test_parsers.py` runs against saved HTML
  fixtures to catch regressions early — if screener.in changes its markup, update the fixtures and parsers together.
- **`screener_get_company_insights` values are genuinely locked without login** — this isn't a scraping trick to get
  around, screener.in simply doesn't send the numbers to anonymous requests. With valid credentials and a successful
  login, the tool currently still reports metric names only (numeric-value parsing for the authenticated table layout
  is a follow-up, since it couldn't be verified without a live logged-in session during development).
- **Respectful by design**: a single shared HTTP client, a descriptive `User-Agent`, retry/backoff only on
  429/5xx/timeouts, a configurable minimum delay between requests (default 1.5s), and a defense-in-depth check
  (`robots.py`) against screener.in's `robots.txt` disallow rules. No CAPTCHA or bot-detection bypass of any kind.
- Intended for personal/educational use consistent with screener.in's terms and your own account's usage limits —
  not a redistribution or resale of screener.in's data.

## Development

```bash
uv sync
uv run pytest
uv run screener-mcp-pro   # runs the server over stdio
```

To inspect tools interactively:

```bash
npx @modelcontextprotocol/inspector uv run screener-mcp-pro
```

## License

MIT — see [LICENSE](LICENSE).