Skip to main content
Glama
Screener India MCP

Screener India MCP

Screener India MCP

The rate-safe, source-traced Screener.in server for AI assistants.

Ask Claude (or any MCP client) about Indian NSE/BSE companies and get Screener.in fundamentals — ratios, 10-year statements, quarterly trends, shareholding, peers, price history, documents and screens — without getting your network or account blocked, and with every number traceable to the page it came from.

License: MIT Python MCP

Personal research only. Screener.in's terms allow personal, non-commercial viewing. This project is not affiliated with or endorsed by Screener.in / Mittal Analytics. It does not redistribute any Screener data; everything stays on your machine. Not investment advice.


Why another Screener MCP?

There are already a few. This one exists because of what went wrong with them in real use:

Problem with existing tools

What Screener India MCP does

Each process throttles itself, so two or three running together trip Screener's limits and get the network blocked

One machine-wide governor: every process shares one request spacing (≥ 2 s, default 3 s), one daily budget and one cool-down, enforced with a file lock

After a block they keep hammering, which makes the block longer

Block-aware: a refusal (HTTP 403/429/503 or a refused connection) starts a cool-down of 30 min → 2 h → 6 h → 24 h, and answers come from cache, clearly marked stale

Passwords sit in plain-text config, or an AI tool accepts the password in chat

Log in once: the password lives in your OS secure store (Windows Credential Manager / macOS Keychain / Linux Secret Service). There is no tool that accepts a password. Silent session expiry is detected and it logs in again by itself

"Red flags" means handing raw tables to the AI and hoping

12 deterministic red-flag checks with the evidence attached — same page, same answer, every time

Numbers with no source

Every response carries provenance: source URL, fetch time, cached/stale, consolidated vs standalone

Some tools expose shell commands, file writes or data syncs to the AI

14 read-only tools (annotated readOnlyHint), no file writes, no shell, no bulk mirroring

One company look-up = many page loads

A company page is fetched once and reused for overview, statements, trend, red flags, shareholding and documents

Related MCP server: DocStoX

Tools

Tool

What it gives

Requests

company_snapshot

Best first call: ratios, sector/industry, pros/cons, growth, 8-quarter trend, red flags, latest shareholding, recent documents

1

company_overview

Market cap, P/E, book value, ROCE, ROE, 52-week range, about, classification, compounded growth

1 (shared)

financial_statement

Quarters, P&L, balance sheet, cash flow or ratios history as periods × rows

1 (shared)

earnings_trend

Quarterly sales/profit/margin/EPS with YoY growth and accelerating / steady / decelerating

1 (shared)

red_flags

12 rule-based checks (cash conversion, receivable & inventory days, other income, leverage, debt vs sales, profit vs sales, falling returns, promoter selling, low tax, CWIP, share-capital increase)

1 (shared)

shareholding

Promoter / FII / DII / public history, quarterly or yearly

1 (shared)

documents

Announcements, annual reports, credit ratings, concall transcripts / presentations / recordings

1 (shared)

peers

Industry peer table

+1

price_history

Price with 50/200-DMA, volume and delivery %, or P/E, margins, EV/EBITDA, P/B, Mcap/Sales history

+1

compare_companies

Side-by-side valuation, returns, margins and growth for 2–6 companies

1 per company

search_company

Find the symbol from a name

1

run_screen

Any Screener query, e.g. Return on capital employed > 20 AND Debt to equity < 0.3 (needs login)

1

theme_screen

12 ready-made screens (quality compounders, earnings acceleration, margin expansion, turnaround…) (needs login)

1

service_status

Login state, requests used/left today, cool-down, cache

0

"shared" = served from the same cached company page, so asking several of these costs one request.

Install

pipx install screener-india-mcp        # or: uv tool install screener-india-mcp

Not on PyPI yet? Install from GitHub:

pipx install git+https://github.com/indrajitdaspiramal-dotcom/screener-india-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "screener-india": { "command": "screener-india-mcp" }
  }
}

Claude Code

claude mcp add screener-india -- screener-india-mcp

Any other MCP client: run screener-india-mcp (stdio), or screener-india-mcp serve --http for streamable HTTP on 127.0.0.1:8631.

Optional: log in once (for screens)

Company data works without an account. Screens need a (free) Screener.in login:

screener-india-mcp login        # asks for email, then the password with hidden typing
screener-india-mcp status       # shows login state and today's budget
screener-india-mcp logout       # removes it

The password goes straight into your OS keyring and is never printed, logged or sent anywhere except Screener's own login form. When Screener ends the session, the server logs in again by itself. Headless Linux without a keyring: set SCREENER_EMAIL and SCREENER_PASSWORD (less safe).

Politeness settings

Environment variables can make the server more polite, never less:

Variable

Default

Limit

SCREENER_MIN_INTERVAL

3 s between requests

never below 2 s

SCREENER_DAILY_BUDGET_ANON

40 requests/day without login

max 60

SCREENER_DAILY_BUDGET

300 requests/day with login

max 1000; 0 = no daily cap (account owner's choice; spacing and cool-down still apply)

SCREENER_STATE_DIR, SCREENER_CACHE_DIR

OS defaults

—

Pages are cached locally (company pages 6 h, prices 3 h, search 7 days). When the budget is spent or Screener is cooling us down, cached answers are still served, marked stale: true.

Using it as a library

from screener_india_mcp.service import Screener

s = Screener()
snap = s.snapshot("TCS")
print(snap["overview"]["ratios"]["pe"], snap["red_flags"]["summary"])

BSE-only and SME companies live on Screener under their BSE scrip code (e.g. /company/530215/), not the ticker. Pass any code you know, or use the code as the symbol; otherwise the library tries a Screener search and accepts only an unambiguous match (it never guesses between two companies). A match that worked is remembered in aliases.json in the state folder.

s.set_bse_codes({"KINGSINFR": "530215", "GENUSPRIME": "532425"})

When a company's consolidated page is thin (fewer than 8 quarters or 5 years — common right after a subsidiary is formed), the standalone page is fetched too. The latest figures and ratios stay consolidated and older columns are filled from standalone; each table's basis list says which columns are which, and growth or red-flag checks never compare across the join. If the consolidated page is too new for trailing-12-month figures (under 4 quarters), the standalone page is used instead. Responses say what happened (view, view_note, history, history_fill).

Batch jobs share the same machine-wide governor as the MCP server, so a nightly script and an assistant session can run side by side without tripping Screener's limits.

Development

git clone https://github.com/indrajitdaspiramal-dotcom/screener-india-mcp
cd screener-india-mcp
pip install -e ".[dev]"
pytest

Tests use synthetic fixtures (invented company, invented numbers) that copy only the page structure; no Screener.in content is stored in this repository. Tests never touch the network or your real keyring.

Acknowledgements

Ideas were drawn from earlier open-source work, with thanks: LogeshR15/screener-mcp (MIT; the "table with the most company links" approach to screen results), screener-ai-tool (MIT; price-chart endpoint and document lists) and the Printing Press screener CLI (Apache-2.0; quarterly trend idea). The code here is an independent implementation.

License

MIT © 2026 Indrajit Das

Available Tools

14 tools
company_overviewB
Read-onlyIdempotent

Key ratios (market cap, P/E, book value, ROCE, ROE, 52-week range…), about, sector/industry, pros/cons and 10/5/3-year compounded growth. view: auto | consolidated | standalone.

Inputs: symbol (required), view.

company_snapshotA
Read-onlyIdempotent

Best first call. One request gives: key ratios, sector/industry, pros/cons, compounded growth, 8-quarter earnings trend, deterministic red-flag checks, latest shareholding and recent documents. symbol = NSE symbol (TCS) or BSE code (500570).

Inputs: symbol (required).

compare_companiesB
Read-onlyIdempotent

Side-by-side valuation, returns, margins and growth for 2–6 companies.

Inputs: symbols (required).

documentsB
Read-onlyIdempotent

Links to exchange announcements, annual reports, credit ratings and concall transcripts / presentations / recordings. kind: all | announcements | annual_reports | credit_ratings | concalls.

Inputs: symbol (required), kind, limit.

earnings_trendB
Read-onlyIdempotent

Quarterly sales/profit/margin/EPS with year-on-year growth and whether growth is accelerating, steady or decelerating.

Inputs: symbol (required), quarters.

financial_statementC
Read-onlyIdempotent

A full statement as periods × rows. statement: quarters | profit_loss | balance_sheet | cash_flow | ratios. periods: keep only the latest N columns (0 = all).

Inputs: symbol (required), view, periods, statement.

peersB
Read-onlyIdempotent

Peer comparison table for the company's industry (price, P/E, market cap, quarterly growth, ROCE).

Inputs: symbol (required).

price_historyC
Read-onlyIdempotent

Daily history. metric: price (with 50/200-day averages and volume) | pe | margins | ev_ebitda | pb | mcap_sales. days snaps to 30, 90, 180, 365, 1095, 1825, 3652 or 10000.

Inputs: symbol (required), days, metric.

red_flagsB
Read-onlyIdempotent

Twelve fixed, explainable checks on reported numbers: cash conversion, debtor/inventory days, other-income share, leverage, debt vs sales growth, profit vs sales growth, falling returns, promoter selling, low tax, CWIP build-up, share-capital increase. Each with evidence.

Inputs: symbol (required).

run_screenA
Read-onlyIdempotent

Run a Screener.in query, e.g. "Return on capital employed > 20 AND Debt to equity < 0.3". Needs a Screener.in login set up once with screener-india-mcp login.

Inputs: query (required), sort, limit, order.

search_companyA
Read-onlyIdempotent

Find a company's Screener.in symbol from its name or part of its ticker (e.g. "caplin", "hdfc bank").

Inputs: query (required), limit.

service_statusB
Read-onlyIdempotent

Login state, requests used/remaining today, cool-down status and cache size.

Inputs: no named parameters.

shareholdingB
Read-onlyIdempotent

Promoter / FII / DII / government / public holding history. period: quarterly | yearly.

Inputs: symbol (required), period.

theme_screenA
Read-onlyIdempotent

Ready-made screens (quality compounders, earnings acceleration, margin expansion, turnaround…). Call with no theme to list them. Needs a login like run_screen.

Inputs: limit, theme.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 14 tools

    Disambiguation3/5

    Most tools are conceptually distinct, but company_snapshot duplicates data from company_overview, earnings_trend, red_flags, shareholding, and documents, so agents must infer when to use summary vs detail. Descriptions label snapshot as the best first call, which helps, but boundaries remain fuzzy.

    Naming Consistency3/5

    All names use snake_case, but the pattern mixes verb_noun (search_company, compare_companies, run_screen) with noun phrases (company_snapshot, financial_statement, shareholding, peers). Readable but not a predictable single convention.

    Tool Count4/5

    14 tools is reasonable for a comprehensive financial research server and sits in the recommended range, though the aggregate snapshot plus several overlapping detail tools makes the set slightly redundant.

    Completeness5/5

    The toolset covers the full research workflow: symbol lookup, snapshot/overview, statements, trends, red flags, shareholding, documents, peers, price history, comparisons, and both custom and themed screening. No obvious lifecycle gaps for the stated Screener.in domain.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to perform deep Indian stock research with fundamentals, forensic scores, DCF valuation, screening, and news for 6000+ NSE/BSE stocks.
      19 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects AI assistants over the Model Context Protocol to live NSE and BSE data, enabling research on Indian listed companies — quotes and price history, quarterly and annual fundamentals, valuation and peer comparison, shareholding, FII/DII flows, F&O and index options, screening, IPOs, corporate actions, filings and market news. Read-only, with no local setup required.
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to search, screen, and analyze 8,200+ NSE and BSE listed securities through 55 tools covering live quotes, financials, technical indicators, FII/DII flows, option chains, filings, IPOs, bulk deals, and portfolio P&L.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to search, screen and analyze all 8,200+ NSE and BSE listed stocks, covering live quotes, financials, technical indicators, FII/DII flows, option chains, filings, IPOs and portfolio tracking through 55 tools.
      -