Screener India MCP
Read-only MCP server for Indian NSE/BSE research: company fundamentals, screens, and safe Screener.in access.
Search companies by name or ticker.
Get a one-call company snapshot: ratios, pros/cons, growth, 8-quarter trend, red flags, shareholding, and documents.
Fetch company overviews and full financial statements (quarters, P&L, balance sheet, cash flow, ratios).
Analyze quarterly earnings trends and 12 rule-based red flags.
View shareholding history, documents/announcements, peers, and price/valuation history.
Compare 2–6 companies side by side.
Run custom Screener queries and ready-made theme screens (requires login).
Check login state, daily request budget, cool-down, and cache via service_status.
All tools are read-only; responses use caching/rate limiting and include source provenance.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Screener India MCP give me a snapshot of TCS with red flags"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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 |
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 |
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 |
| Best first call: ratios, sector/industry, pros/cons, growth, 8-quarter trend, red flags, latest shareholding, recent documents | 1 |
| Market cap, P/E, book value, ROCE, ROE, 52-week range, about, classification, compounded growth | 1 (shared) |
| Quarters, P&L, balance sheet, cash flow or ratios history as periods × rows | 1 (shared) |
| Quarterly sales/profit/margin/EPS with YoY growth and accelerating / steady / decelerating | 1 (shared) |
| 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) |
| Promoter / FII / DII / public history, quarterly or yearly | 1 (shared) |
| Announcements, annual reports, credit ratings, concall transcripts / presentations / recordings | 1 (shared) |
| Industry peer table | +1 |
| Price with 50/200-DMA, volume and delivery %, or P/E, margins, EV/EBITDA, P/B, Mcap/Sales history | +1 |
| Side-by-side valuation, returns, margins and growth for 2–6 companies | 1 per company |
| Find the symbol from a name | 1 |
| Any Screener query, e.g. | 1 |
| 12 ready-made screens (quality compounders, earnings acceleration, margin expansion, turnaround…) (needs login) | 1 |
| 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-mcpNot on PyPI yet? Install from GitHub:
pipx install git+https://github.com/indrajitdaspiramal-dotcom/screener-india-mcpClaude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"screener-india": { "command": "screener-india-mcp" }
}
}Claude Code
claude mcp add screener-india -- screener-india-mcpAny 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 itThe 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 |
| 3 s between requests | never below 2 s |
| 40 requests/day without login | max 60 |
| 300 requests/day with login | max 1000; |
| 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]"
pytestTests 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 toolscompany_overviewBRead-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_snapshotARead-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_companiesBRead-onlyIdempotent
Side-by-side valuation, returns, margins and growth for 2–6 companies.
Inputs: symbols (required).
documentsBRead-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_trendBRead-onlyIdempotent
Quarterly sales/profit/margin/EPS with year-on-year growth and whether growth is accelerating, steady or decelerating.
Inputs: symbol (required), quarters.
financial_statementCRead-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.
peersBRead-onlyIdempotent
Peer comparison table for the company's industry (price, P/E, market cap, quarterly growth, ROCE).
Inputs: symbol (required).
price_historyCRead-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_flagsBRead-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_screenARead-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_companyARead-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_statusBRead-onlyIdempotent
Login state, requests used/remaining today, cool-down status and cache size.
Inputs: no named parameters.
theme_screenARead-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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
Hosted MCP server for Indian NSE/BSE stock research: 59 tools for quotes, financials and ratios, peers, shareholding and pledge, filings with extracted facts, screens, F&O and FII/DII context. Source and freshness on every answer; no buy/sell calls.
Indian stocks: NSE/BSE filings read by AI with price reactions, fundamentals, IPOs and FPI flows.
48 tools for ~8,000 NSE & BSE stocks: quotes, screener, financials, filings, FII/DII, options
SEC-filed company financials with filing citations, plus market data, for AI agents
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to perform deep Indian stock research with fundamentals, forensic scores, DCF valuation, screening, and news for 6000+ NSE/BSE stocks.19 npm1MIT

DocStoXofficial
AlicenseNot gradedqualityCmaintenanceConnects 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- FlicenseNot gradedqualityAmaintenanceEnables 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.-
- FlicenseNot gradedqualityAmaintenanceEnables 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.-