screener-mcp
Provides recent headlines and broker target mentions from Google News, supporting recent-news lookup and analyst target context for Indian stocks.
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-mcp Compare ITC and HINDUNILVR on all key ratios"
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-mcp
An MCP (Model Context Protocol) server that gives Claude live access to Screener.in, NSE, and MCX data — turning Claude into a research assistant for Indian stocks.
Report an issue · LinkedIn · logeshl2003@gmail.com
screener-mcp connects Claude (Claude Code, Claude Desktop, or any MCP client) to Indian equity data: company financials, stock screening, annual reports, earnings calls, corporate announcements, and a local portfolio tracker. Point Claude at a company or a screen, and it does the research using real, current data instead of its training-data knowledge of the stock.
What you can do
"Compare ITC and HINDUNILVR on all key ratios"
"Find low-debt, high-ROCE chemical stocks"
"Quality stocks within 10% of their 52-week low"
"Has MSUMI fallen more than the auto sector over the last 60 days?"
"What are analysts' target prices for TMPV, and what's the latest news?"
"Summarize the key risks from Reliance's 2024 annual report"
"What did TCS management say about margins in Q3FY25?"
"What are the red flags in Asian Paints?"
"Show me recent NSE announcements for HDFCBANK"
"Find recent bulk deals in a stock"
"Track my portfolio and show live P&L"
"Save a research note on TITAN — strong Q3, watch margins"Related MCP server: Finance Research Agent
Quick start
Requires uv — pip install uv or brew install uv.
claude mcp add screener -s user -- uvx --from 'screener-mcp[ai]' screener-mcpThis installs the full server, including document analysis (annual reports, earnings calls). If you only need company research and stock screening, drop the extra for a much lighter install:
claude mcp add screener -s user -- uvx screener-mcpCore vs.
[ai]: the base package covers company data, screening, NSE announcements, and portfolio tracking. The[ai]extra addspdfplumber,chromadb, andsentence-transformers(~1–2GB, via torch) to powerask_company_researchandsearch_market_commentary(and the management-guidance part ofget_forward_outlook). Without it, those tools return a "not installed" error — everything else works normally.
Using Claude Desktop instead of Claude Code? See Claude Desktop setup.
Verify it works
claude mcp list
# screener stdio ConnectedThen try a few prompts in Claude:
"Search for Asian Paints"
"Give me the company overview for TCS"
"Run the defense theme screen"If these return real data, the server is working end to end.
What it provides
Company research — financials (incl. year-end P/E, P/B, ROE and debt-to-equity history), shareholding trends with promoter/pledge assessment, peer comparison, rule-based red-flag checks (no login required)
Stock screening — custom Screener.in-style queries with
AND/OR/ parentheses, pre-built thematic screens (sector themes start from the companies actually in the sector), and technical clauses (52-week distance, RSI, DMA, volume spikes). Junk rows are filtered out by default. Fundamental screens need a free Screener.in login; technical-only screens don'tPrice-action context — quality stocks near 52-week lows in one call, and a stock's move vs its sector index and the Nifty 50
Valuation & quality context — P/E and ROCE vs the industry median for up to 20 stocks at once, and moat proxies: revenue share, rank, industry concentration, and how durable returns and margins have been
Forward-looking & Street view — analyst EPS/revenue estimates and target prices, order wins and capex filings, management guidance from earnings calls, and recent news
Document analysis — ask questions over annual reports and earnings call transcripts using a local RAG pipeline
Corporate events — NSE announcements (incl. credit and ESG rating actions), bulk deals by company or investor, insider trading disclosures
Market & research — commodity price context, local research notes
Portfolio — a private, local holdings tracker with live P&L
30 tools in total — full reference below. Every tool returns the same response envelope, so partial or degraded data is always explicit.
Two prompts — deep_dive(symbol) and value_screen(min_roce, max_pe) — package common research workflows; clients that support MCP prompts show them as slash commands.
Speaks MCP protocol 2026-07-28 (built on the v2 Python SDK) and still serves clients on 2025-11-25 and earlier.
Example workflows
Compare companies —
"Compare ITC and HINDUNILVR on all key ratios"→compare_companiesScreen for opportunities —
"Find low-debt, high-ROCE small caps"→screen_by_themeorscreen_stocksFind pullbacks —
"High-ROCE, low-debt stocks near their 52-week low"→get_52_week_low_candidates, orscreen_stocks("Return on capital employed > 15 AND 52 week low distance < 10")Market vs company-specific —
"Is this fall sector-wide or just this stock?"→compare_to_sectorWhat the Street thinks —
"Analyst targets and recent news for TMPV"→get_analyst_targets,get_recent_newsIs it cheap for its sector? —
"Which of these 15 stocks trade below their industry P/E?"→get_relative_valuation, orscreen_stocks(..., peer_relative=True)Moat check —
"Is MSUMI a market leader with durable returns?"→get_moat_signalsFuture growth —
"What's the order pipeline and guidance for BEL?"→get_forward_outlookRead an annual report —
"What are the key risks in Reliance's 2024 annual report?"→ask_company_research(..., year=2024)Read an earnings call —
"What did TCS say about margins in Q3FY25?"→ask_company_research(..., quarter="Q3FY25")Across years —
"How has ITC described cigarette taxation over the years?"→ask_company_research(..., doc_type="annual_report")Spot red flags —
"What are the red flags in Asian Paints?"→analyze_red_flagsTrack NSE activity —
"Show recent announcements for HDFCBANK"→get_company_announcementsResearch bulk deals —
"Any recent bulk deals in TITAN?"→get_bulk_deals("TITAN");"What has SBI Mutual Fund bought in bulk?"→get_bulk_deals(name="SBI Mutual Fund")Track a portfolio —
"Add 10 shares of INFY at ₹1500 to my portfolio"→add_portfolio_stockSave research —
"Save a note on TITAN — strong Q3, watch margins"→notebook_ai
Architecture
Claude (Code / Desktop)
│ MCP
▼
screener-mcp
│
├──► Screener.in (financials, ratios, screening, industry pages, price history)
├──► NSE India (announcements, order wins, bulk deals, insider trades)
├──► Yahoo Finance (analyst consensus & estimates, commodity benchmarks)
└──► Google News (recent headlines, broker target mentions)
│
▼
Research data (parsed, cached, indexed)
│
▼
Claude reasons over the data and answersscreener-mcp fetches and normalizes the data; Claude does the analysis and explains it in plain language.
Installation options
Recommended
# Full install (company research, screening, documents, everything)
claude mcp add screener -s user -- uvx --from 'screener-mcp[ai]' screener-mcp
# Lightweight install (skip document analysis)
claude mcp add screener -s user -- uvx screener-mcpClaude Code
Use the claude mcp add commands above. Confirm with claude mcp list.
Claude Desktop
Claude Desktop doesn't read claude mcp add — edit its config file directly.
1. Install uv if needed: brew install uv (or pip install uv)
2. Open the config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
(In the app: Settings → Developer → Edit Config.)
3. Add the screener server:
{
"mcpServers": {
"screener": {
"command": "uvx",
"args": ["--from", "screener-mcp[ai]", "screener-mcp"],
"env": {
"SCREENER_USERNAME": "your@email.com",
"SCREENER_PASSWORD": "yourpassword"
}
}
}
}Claude Desktop does not inherit your shell environment, so credentials must go in the "env" block here — see Credentials. Leave "env" out entirely if you only want the no-login company-research tools.
spawn uvx ENOENTon launch? Claude Desktop starts with a minimalPATH. Runwhich uvxand use the absolute path (e.g./opt/homebrew/bin/uvx) as"command".
4. Quit Claude Desktop completely (Cmd+Q on macOS) and reopen it.
5. Check the tools icon in the message composer — screener should list its 30 tools. Then ask: "Search for Asian Paints".
Server not showing up? Check Settings → Developer for its status, and the logs at
~/Library/Application Support/Claude/logs/mcp-server-screener.log(macOS) or%APPDATA%\Claude\logs\(Windows). Invalid JSON — often a stray trailing comma — makes Claude Desktop skip every server silently.
pip / PyPI
The package is published on PyPI as screener-mcp. uvx (above) runs it without a persistent install; to install it into an environment instead:
pip install screener-mcp # core
pip install "screener-mcp[ai]" # with document analysisThen run it directly, or point claude mcp add at the screener-mcp entry point it installs.
Developer (local clone)
git clone https://github.com/LogeshR15/screener-mcp
cd screener-mcp
python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .
claude mcp add screener -s user -- \
$(pwd)/.venv/bin/python3.11 \
$(pwd)/run_server.pyAny Python 3.11+ works — e.g.
python3.12 -m venv .venv— just pointclaude mcp addat that interpreter.pip install -e .failing with "editable mode currently requires a setuptools-based build"? Upgradepipin the venv first (as above), then retry.
Already cloned it and using Claude Desktop? Point the config at your venv interpreter instead of uvx:
{
"mcpServers": {
"screener": {
"command": "/absolute/path/to/screener-mcp/.venv/bin/python3.11",
"args": ["/absolute/path/to/screener-mcp/run_server.py"]
}
}
}Advanced: HTTP and Docker
For remote/network deployment rather than a local stdio process, see Remote HTTP server and Docker below.
Credentials
Capability | Needs Screener.in login? |
Company research (financials, ratios, shareholding, peers, red flags) | No |
Stock screening with fundamental clauses ( | Yes |
Technical-only screens, | No (a login lets |
| No ( |
NSE announcements, bulk deals, credit ratings, commodities | No |
Document analysis, notebook, portfolio | No |
To enable screening:
1. Register free at screener.in/register
2. Claude Code / manual runs — add to ~/.zshrc or ~/.bashrc, then reload (source ~/.zshrc) and restart Claude Code:
export SCREENER_USERNAME="your@email.com"
export SCREENER_PASSWORD="yourpassword"3. Claude Desktop — it does not read your shell profile, so the same two values must go in the "env" block of claude_desktop_config.json (see Claude Desktop setup):
"env": {
"SCREENER_USERNAME": "your@email.com",
"SCREENER_PASSWORD": "yourpassword"
}Never commit real credentials — the values above are placeholders.
Tools — 30 total
Grouped by category. See Example workflows for the ones you'll reach for most.
Company Research
Tool | What it does | Login needed |
| Find company by name or symbol | No |
| Key ratios, price, 52W range, NSE/BSE codes, about, Screener's pros/cons | No |
| P&L (TTM separate) / Balance Sheet / Cash Flow / Ratios incl. year-end P/E, P/B, ROE, debt-to-equity | No |
| Last 8 quarters of results | No |
| 8-quarter holding trends per category, promoter-group detection, promoter pledge | No |
| Sector peer comparison table | No |
| 2–6 stocks side by side, with point-in-time red flags; interactive dashboard (MCP App) where supported, JSON everywhere | No |
| All data combined for deep analysis (same windows as the standalone tools) | No |
| Rule-based red-flag checks over the full history, each with evidence and thresholds | No |
Stock Screening
Tool | What it does | Login needed |
| Screener.in query plus technical clauses (52W distance, RSI, DMA, volume spike) | Fundamental clauses only |
| Quality filters + proximity to 52-week low, with overview fields per match | No |
| P/E and ROCE vs the industry median for up to 20 stocks at once | No |
| Stock's return vs its sector index and Nifty 50, with a market-vs-company verdict | No |
| Pre-built thematic screens — every theme's criteria are in the tool description | Query themes only |
Document Analysis
Tool | What it does | Extra deps needed |
| List annual reports & earnings call transcripts | No |
| Ask a question over a company's annual reports and earnings calls — all recent ones, one | Yes |
| Search a question across multiple companies' already-indexed documents at once | Yes |
ask_company_researchandsearch_market_commentarybuild on the same cache — the former indexes a company's documents and searches them (one or many); the latter searches only what's already indexed across several symbols (good for "which of these companies mentioned Y?").
Corporate Events
Tool | What it does | Login needed |
| NSE corporate announcements with category filter — incl. | No |
| NSE bulk deals by company ( | No |
| SEBI PIT promoter/KMP/designated-person trade disclosures, no size threshold (both NSE PIT feeds merged) | No |
Market & Research
Tool | What it does | Login needed |
| Recent news headlines for a company (Google News), newest first | No |
| Consensus target price (mean/median/high/low, analyst count, rating split) + broker targets in recent headlines | No |
| Analyst EPS/revenue estimates, order wins and capex filings, management guidance from the latest earnings call | No ( |
| Revenue share/rank and industry concentration (HHI), plus ROCE, margin and promoter-holding durability | No |
| International benchmark price, period moves, ≈INR price + exposed companies' symbols (incl. wheat; tobacco and wood pulp as exposure-only) | No |
| Save, read, and AI-summarize research notes locally | No |
Portfolio
Tool | What it does | Login needed |
| Add/merge a holding into your local portfolio (quantity-weighted avg cost) | No |
| Overwrite quantity/avg price on an existing holding (partial sell, cost correction) | No |
| Remove a holding entirely | No |
| View holdings with live price, P&L (₹ and %), and weight | No |
Stored locally at
~/.screener-mcp/portfolio.json— no account, no external service, nothing leaves your machine.
Document analysis
Document analysis ([ai] extra) uses a local RAG pipeline:
ask_company_research("TCS", "What are the key risks?", year=2024)
1. Fetch PDF link from Screener.in / NSE
2. Download and parse with pdfplumber — two-column pages are split at the
gutter, rotated/mirrored decorative text is dropped
3. Chunk into 500-word overlapping segments
4. Embed with sentence-transformers (runs locally, no API key needed)
5. Store in ChromaDB (~/.screener-mcp/chroma_db/)
6. Semantic search, re-ranked: question keywords boosted, BRSR boilerplate
demoted (unless the question is about ESG), one hit per ~3-page window
7. Return the top excerpts, each trimmed to ~900 characters around the
question's terms, with document and pageResults are cached — the same report isn't re-downloaded or re-processed. Indexes built by an older version of the pipeline are rebuilt automatically on next use (from the cached PDF). Each document's freshness reports last_indexed_at, the PDF's content_sha256, its etag / last_modified, and source_changed (a HEAD check against the live PDF; null when the server gives no validators). If a report was revised or refiled, pass force_reindex=True to rebuild the index. The manifest lives at ~/.screener-mcp/index_manifest.json.
Stock screening
Pre-built themes
Query themes run a Screener query across the whole market:
undervalued_small_cap Small caps < ₹5000 Cr, ROCE > 15%, low debt, P/E < 20
high_roce_low_debt ROCE > 20%, debt to equity < 0.3
compounders 15%+ growth: revenue, profit, ROE, ROCE
turnaround Strong recent profit recovery
rising_profit_falling_price Profit up 15%+/yr over 3 years, price down over 1 year, P/E < 15
improving_roce ROCE > 15% and above last year's and its 5-year average
hidden_gems Small cap, high ROCE, strong growth
dividend_aristocrats Yield > 2%, dividend paid in each of the last 2 years, 3y payout > 20%
qarp Quality at reasonable price
micro_cap_growth High-growth micro caps < ₹1000 CrSector themes start from the companies actually in the sector — Screener's query language has no industry field — then filter them:
defense Nifty India Defence + Aerospace & Defense and Shipbuilding industries
ev_theme Nifty EV & New Age Automotive constituents
chemicals Specialty Chemicals industry + Nifty Chemicals
railways Railway Wagons industry + a curated list of railway PSUs/suppliers
renewable_energy Curated list of wind/solar makers and green power producersEvery result says which universe it came from (data.universe), and screen_by_theme's description carries each theme's exact criteria. Both screen_by_theme and screen_stocks take page to go past the first page of results.
Custom screen syntax
Market Capitalization < 5000 AND Return on capital employed > 15 AND Debt to equity < 0.5
Profit growth 5Years > 20 AND Sales growth 5Years > 15 AND Debt to equity < 0.3
Dividend yield > 3 AND Return on equity > 15 AND Pledged percentage < 5Supported operators: > < >= <= =, combined with AND, OR and parentheses
Full field list in CONTRIBUTING.md.
Technical clauses
Mix these with fundamental clauses using AND, OR and parentheses:
52 week low distance < 10 % above the 52-week low
52 week high distance > 30 % below the 52-week high
RSI < 30 14-day RSI
Price above 200 DMA also below / 20, 50, 200 DMA / "50 DMA above 200 DMA"
Price vs 50 DMA < -5 % above (+) or below (−) a moving average
Volume vs 20 day average > 2 today's volume ÷ 20-day average volumeReturn on capital employed > 15 AND Debt to equity < 0.5 AND 52 week low distance < 10
RSI < 30 AND Price above 200 DMA (technical-only: no login needed)
(Return on capital employed > 20 OR Return on equity > 25) AND Price above 200 DMA
Return on capital employed > 15 AND (RSI < 30 OR 52 week low distance < 5)Fundamental clauses run on Screener.in as usual. The technical clauses are then evaluated against up to max_candidates (default 150) of those matches, using daily price history from Screener's public chart API. A query with only technical clauses scans an NSE index instead (universe, default nifty500; also nifty50, midcap100, smallcap100, smallcap250, bank, it, auto, pharma, fmcg, metal, realty, energy, defence, chemicals, ...). If some candidates weren't checked, the response has partial: true and a reason. The 52-week range is based on closing prices.
When OR groups contain no technical clauses, they go to Screener unchanged, since Screener supports them. When a technical clause sits under an OR, each alternative runs as its own screen, up to 6. The results are merged, and each result's matched_groups shows which alternatives it satisfied.
Result hygiene
Screens sorted by growth used to fill up with tiny illiquid names showing one-off numbers. Two guards are now on by default:
min_market_cap(₹100 Cr) is added to the Screener query unless your query already has aMarket Capitalizationclause. Set it to0to turn it off.exclude_flaggeddrops rows with implausible numbers and lists them underexcluded_for_data_quality. The checks are: P/E below 1, a quarterly profit jump over 500% on a small base, quarterly profit above sales, negligible sales, a price below ₹1, and a dividend yield above 25% (a special dividend or stale price). Set it toFalseto keep these rows, marked withdata_quality_flags.
Pass peer_relative=True to add each result's P/E and ROCE compared with its industry median.
Keeping it working
Screener.in changes its pages without notice. A scheduled GitHub Action (canary.yml) runs scripts/canary.py every day. It checks the real tools against known companies: overviews, the standalone fallback, financial tables, symbol resolution, a technical screen, sector comparison and peers. If a check fails, it opens a "Live canary failing" issue. NSE checks only warn, because NSE often blocks GitHub's IPs. You can run it locally with python scripts/canary.py.
Response envelope
Every tool returns the same shape:
{
"status": "ok | partial | error",
"partial": false,
"warnings": ["MSUMI publishes no consolidated financials — showing standalone figures instead."],
"data": { "...": "..." },
"missing_fields": ["pe"],
"reason": "Screener.in's page had no value for these fields.",
"meta": { "symbol": "MSUMI", "financial_type": "standalone", "requested_symbol": "MOTHERSONWIR", "interpreted_as": "MSUMI" },
"error": { "type": "symbol_ambiguous", "message": "...", "candidates": [{ "symbol": "TMPV", "name": "Tata Motors Passenger Vehicles Ltd" }] }
}Blank source fields show up in
missing_fieldswithstatus: "partial", and their values arenull, never""or0.Companies without subsidiaries have a blank
/consolidated/page on Screener. The server falls back to standalone figures and says so inwarnings.Non-canonical symbols like
MOTHERSONWIRresolve through Screener search. A confident match proceeds and is recorded inmeta.interpreted_as. An ambiguous one returnserror.candidates(top 3), so you can retry in one call.Errors are flagged on the wire. When
statusis"error", the MCP result also hasisError: true, so clients treat the call as failed rather than as an empty success.Slow tools report progress. Screens, full analyses, forward outlook and document search send a progress notification every few seconds (when the client asks for progress), so a long call never looks hung.
Implausible ratio history, such as days-based metrics out of range or a Cash Conversion Cycle that doesn't equal debtor + inventory − payable days, is kept but marked
data_quality_flag: true, with a reason.
Remote HTTP server
By default this runs over stdio — a local process, used by claude mcp add, Claude Desktop, and similar clients. Some integrations — any client that asks for an HTTPS Server URL — instead need a network server.
Run it with HTTP transport:
MCP_TRANSPORT=streamable-http PORT=8000 python run_server.py
# Serves MCP over HTTP at http://<host>:8000/mcpEnv vars:
Variable | Purpose | Default |
| Screener.in login email (needed for screening tools) | — |
| Screener.in password | — |
|
|
|
| Port to listen on (HTTP transport only) |
|
| Bind address (HTTP transport only) |
|
| Where the document-analysis vector store is cached |
|
To get a public HTTPS URL, deploy this to any host that can run a long-lived Python process and terminate TLS for you (Render, Railway, Fly.io, a VM behind a reverse proxy, etc.), then point the client at https://your-host/mcp.
A bare
streamable-httpserver has no authentication. If you deploy it publicly, put it behind your platform's access controls (API gateway, IP allowlist, auth proxy) rather than exposing it to the open internet unauthenticated — especially if you setSCREENER_USERNAME/PASSWORD, since anyone who can reach the URL would act as your Screener.in account.
Docker
A Dockerfile is included. It installs the full [ai] extras (document analysis included) — expect a slow first build (~1-2GB with torch).
# Build and tag the image
docker build -t screener-mcp:latest .
# Run it, exposing the HTTP port and setting credentials
docker run -p 8000:9000 \
-e PORT=9000 \
-e SCREENER_USERNAME=you@example.com \
-e SCREENER_PASSWORD=yourpassword \
screener-mcp:latestThen point the client at http://<host>:8000/mcp.
Data sources & limitations
Source | Data provided |
10+ years of financials, ratios, shareholding, peers | |
Announcements, annual reports, bulk deals, insider trading disclosures | |
International commodity benchmarks (COMEX, ICE Brent, NYMEX), USD/INR, analyst consensus targets | |
Google News RSS | Recent headlines, including broker target-price mentions |
Financial data lags by ~1 quarter
Screener.in rate-limits bursts. The client paces requests (
SCREENER_MIN_INTERVAL, default 0.25s) and caps concurrency (SCREENER_MAX_CONCURRENCY, default 3). Any 429 pauses all requests for a shared cooldown, and requests are then retried. Price history is cached in~/.screener-mcp/price_cache: during market hours for 15 minutes, otherwise until the next session. A cold technical screen can take a minute; repeat screens are fast. SetSCREENER_PRICE_CACHE=0to disable the cacheCommodity prices are the international benchmarks MCX contracts track. The INR figure is a plain FX conversion, before import duty and GST, so it's below the MCX quote. Nickel has no free feed and returns
partialget_company_overviewreturnsdata.price_freshness:price_as_of, whether the price is an intraday print or the last close, the previous close and the day's change. A price older than a few days is flagged as staleAnalyst targets come from two sources that cover different brokers and dates, so they won't match: Yahoo Finance's consensus and targets extracted from recent headlines. Treat either as one view, not the market's
For banks, NBFCs and insurers, debt-to-equity and working-capital-day checks are skipped because they aren't meaningful for lenders. Judge these companies on ROE, asset quality and capital adequacy
Document analysis requires machine-readable PDFs (scanned/image-only PDFs may fail)
NSE bulk deals only capture single trades > 0.5% of equity
The NSE-backed tools (
get_company_announcements,get_insider_trading,get_bulk_deals) depend on NSE's public API, which often rate-limits or blocks server IPs. When that happens the tool returnsstatus: "error"witherror.type: "upstream_unavailable". When only some bulk-deal days fail, it returnspartial. An empty list withstatus: "ok"means NSE really had no rows. These tools resolve fuzzy symbols the same way as the Screener tools, and they return anot_on_nseerror for companies listed only on BSE.This is a research tool — not financial advice
Project layout
screener-mcp/
├── run_server.py
├── scripts/canary.py # Daily live check against Screener.in (see .github/workflows/canary.yml)
├── tests/ # Offline tests (no network) + a real-page fixture
└── src/screener_mcp/
├── server.py # MCPServer (MCP SDK v2) — all 30 tool definitions
├── client.py # Screener.in HTTP client + auth
├── core/
│ ├── envelope.py # Standard response envelope for every tool
│ ├── company_page.py # Symbol resolution + page fetch + standalone fallback
│ ├── quality.py # Missing-field detection + ratio sanity bounds
│ ├── technicals.py # Price history → 52W range, DMA, RSI, volume ratio
│ ├── indices.py # NSE index universes + sector benchmarks
│ ├── yahoo.py # Yahoo Finance session (consensus targets, estimates)
│ ├── industry.py # Industry pages → medians, revenue share, HHI
│ ├── nse_client.py # NSE India API (announcements, filings)
│ ├── history.py # Year-by-year series, computed ROE / debt-to-equity, CAGR
│ ├── valuation_history.py # Year-end P/E and P/B from Screener's chart API
│ ├── rag.py # PDF → chunk → embed → query pipeline
│ └── vector_store.py # ChromaDB wrapper
├── parsers/
│ ├── company.py # Screener.in company page parser
│ └── screener.py # Screen results parser
├── ui/
│ ├── stock_comparison.html # compare_companies dashboard (MCP App)
│ └── ext-apps-app-with-deps.js # vendored MCP Apps runtime (MIT)
└── tools/
├── company_tools.py # Company data tools
├── screening_tools.py # Stock screening + themes
├── technical_tools.py # Technical screens, 52W-low candidates, sector-relative
├── analysis_tools.py # Full analysis, rule-based red flags
├── documents.py # Annual reports + earnings calls (RAG)
├── announcements.py # NSE corporate announcements (incl. credit/ESG ratings)
├── shareholders.py # NSE bulk deals (by company and/or investor)
├── insider_trading.py # SEBI PIT insider trading disclosures
├── market_tools.py # Recent news + analyst targets
├── research_tools.py # Relative valuation, moat signals, forward outlook
├── commodities.py # Commodity price analysis
├── notebook.py # Research notes
└── portfolio.py # Local portfolio trackerContributing
See CONTRIBUTING.md — adding a new tool takes ~10 minutes.
git clone https://github.com/LogeshR15/screener-mcp
cd screener-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytestThe test suite is offline — no network, no Screener.in credentials — and checks that the tool registry and the docs still agree with each other. If you add or rename a tool, tests fail until you update EXPECTED_TOOLS in tests/test_tools.py, the server.py docstring, and the README tool table.
Dependency files:
pyproject.toml— the source of truth;[ai]extra adds document analysisrequirements.txt— full install (core + document analysis, pulls in torch)requirements-core.txt— lightweight install, no document-analysis tools
License
MIT © Logesh Ramasamy
Contact
Logesh Ramasamy · logeshl2003@gmail.com · LinkedIn
Available Tools
30 toolsadd_portfolio_stockA
Add a holding to your local portfolio (~/.screener-mcp/portfolio.json).
If you already hold this symbol, the new lot merges into the existing position with a quantity-weighted average price — like a real broker ledger, buying more at a different price updates your average cost rather than overwriting it.
symbol: NSE/BSE symbol (e.g., "RELIANCE") quantity: number of shares in this lot avg_price: price per share for this lot
Examples: add_portfolio_stock("RELIANCE", quantity=10, avg_price=1350) add_portfolio_stock("TCS", quantity=5, avg_price=3800)
Inputs: symbol (required), quantity (required), avg_price (required). Returns: object
analyze_red_flagsARead-only
Rule-based red-flag checks over a company's full history — computed here, each flag with its severity and the numbers behind it:
Promoter holding falling, promoter shares pledged
Leverage (debt-to-equity) and borrowings outgrowing sales
ROCE falling or below 10%
Operating cash flow lagging net profit (and negative CFO)
Sales growing much faster than profit
Debtor / inventory days rising
Profit leaning on other income (one-offs)
Equity dilution
Returns flags (sorted by severity), clean_checks, skipped_checks (e.g. leverage for banks, promoter checks for a company with no promoter), the thresholds used, and not_checked items that need the annual report.
symbol: NSE/BSE symbol
Inputs: symbol (required), financial_type. Returns: object
ask_company_researchARead-only
Ask a question over a company's annual reports and earnings-call transcripts using semantic search — across all recent documents at once, one document type, or a single document.
ask_company_research("TCS", "How has capex strategy evolved?") # 3 ARs + 4 calls ask_company_research("ITC", "Key regulatory risks", doc_type="annual_report") ask_company_research("TCS", "Key risks", year=2024) # one annual report ask_company_research("HDFCBANK", "NIM guidance", quarter="Q3FY25") # one earnings call
Downloads and indexes the PDFs locally on first use (cached after that), then returns the most relevant excerpts (each capped to ~900 characters, with document and page) — BRSR/sustainability boilerplate is ranked down unless the question is about ESG.
doc_type: "all" | "annual_report" | "earnings_call" year: one annual report (e.g. 2024) — implies doc_type="annual_report" quarter: one earnings call (e.g. "Q1FY26") — implies doc_type="earnings_call" pdf_url: search this PDF directly (label it with year or quarter) max_annual_reports / max_earnings_calls: how many recent documents to include when no year/quarter is given force_reindex: re-download and rebuild the index (see each document's freshness.source_changed)
Requires the [ai] extra: pip install 'screener-mcp[ai]'
Inputs: symbol (required), year, pdf_url, quarter, +5 more. Returns: object
compare_companiesARead-only
Side-by-side comparison of 2 to 6 companies: price, market cap, P/E, book value, ROCE, ROE, debt-to-equity, dividend yield, 52-week range, plus point-in-time red-flag checks per company.
Hosts that support MCP Apps (e.g. Claude Desktop) also render an interactive dashboard with the best value in each row highlighted; every host gets the same data as JSON in data.companies.
symbols: list (["ITC", "HINDUNILVR", "NESTLEIND"]) or comma-separated string ("TCS,INFY,WIPRO"). Company names and near-miss symbols are resolved like everywhere else. financial_type: "consolidated" or "standalone"
Examples: compare_companies(["ITC", "HINDUNILVR"]) compare_companies("TCS,INFY,WIPRO,HCLTECH")
Inputs: symbols (required), financial_type. Returns: object
compare_to_sectorARead-only
Has this stock fallen (or risen) more or less than its sector and the market? Separates a market/sector pullback from a company-specific move.
Compares the stock's close-to-close return against its sector index
(auto-picked from its Screener sector, e.g. Nifty Auto, Nifty IT, Nifty
India Defence) and the Nifty 50, over days calendar days plus 7/30/90-day
context windows. Also returns beta and correlation vs the sector, drawdown
from the window high, and a plain-language verdict.
symbol: NSE/BSE symbol days: window in calendar days (5-365, default 30) benchmark: optional index override — nifty50, nifty500, bank, it, auto, pharma, fmcg, metal, realty, energy, defence, chemicals, ...
Examples: compare_to_sector("MSUMI", days=60) compare_to_sector("HDFCBANK", benchmark="private_bank")
Inputs: symbol (required), days, benchmark. Returns: object
get_52_week_low_candidatesARead-only
Quality stocks trading near their 52-week low — in one call.
Combines quality filters (ROCE, debt-to-equity, market cap in ₹ Cr) with proximity to the 52-week low, and returns for each match: current price, 52W high/low, % above the low, RSI/DMA context, and the same clean fields as get_company_overview (P/E, ROCE, ROE, book value, dividend yield, debt-to-equity).
With a Screener login and no universe, scans the whole market via a
Screener query. Otherwise scans an index's constituents (default Nifty
500) and computes debt-to-equity from each match's latest balance sheet.
Examples: get_52_week_low_candidates() get_52_week_low_candidates(min_roce=20, max_debt_to_equity=0.2, max_pct_above_52w_low=5) get_52_week_low_candidates(universe="midcap100", min_market_cap=5000)
Inputs: limit, min_roce, universe, min_market_cap, +2 more. Returns: object
get_analyst_targetsARead-only
Analyst price targets for a stock, from two independent sources:
Consensus (Yahoo Finance): mean / median / high / low target, number of analysts, implied upside vs the current price, and the strong-buy/buy/hold/sell/strong-sell split.
Broker targets mentioned in the last 60 days of news headlines (e.g. "ICICI Securities target ₹370"), with links to each article.
The two come from different broker sets and dates, so they rarely match; both are labelled with their source. Returns partial=true if one source is unavailable, or if the stock has no analyst coverage.
symbol: NSE/BSE symbol or company name
Examples: get_analyst_targets("TMPV") get_analyst_targets("HDFCBANK")
Inputs: symbol (required). Returns: object
get_bulk_dealsARead-only
NSE bulk deals (single trades > 0.5% of a company's equity) — for one company, for one investor across the market, or both.
symbol: restrict to one company ("YESBANK") name: partial investor/entity name ("Jhunjhunwala", "SBI Mutual Fund", "Nalanda") — matched against the deal's client name days: look-back (default 30, max 365; NSE serves one day per request, so only the most recent 90 days are searched)
Pass at least one of symbol / name. Bulk deals miss gradual accumulation — for aggregate FII/DII/promoter holdings use get_shareholding_pattern, for promoter/KMP trades of any size use get_insider_trading.
Examples: get_bulk_deals("ADANIENT", days=60) get_bulk_deals(name="Mutual Fund") get_bulk_deals("TCS", name="SBI Mutual Fund")
Inputs: days, name, symbol. Returns: object
get_commodity_pricesARead-only
Commodity price context and its impact on Indian listed companies.
Returns the international benchmark price the MCX/NCDEX contract tracks
(COMEX gold/silver/copper, Brent, Henry Hub, CBOT wheat, etc.), with
4-week, 52-week and years-period moves and range, USD/INR, and an
approximate INR price (a pure FX conversion — excludes import duty/GST, so
below MCX). Also lists which companies benefit or suffer from price moves
and their symbols (data.watch_symbols) to pass to compare_companies.
commodity: gold | silver | crude_oil | copper | aluminium | zinc | nickel | cotton | natural_gas | steel | wheat | tobacco | wood_pulp (nickel, tobacco, wood_pulp: no free price feed → partial, exposure analysis only) years: history period for the moves and range (1–10, default 5)
Examples: get_commodity_prices("crude_oil") get_commodity_prices("copper", years=3) get_commodity_prices("gold")
Inputs: commodity (required), years. Returns: object
get_company_announcementsARead-only
Fetch recent company announcements (exchange filings) from NSE.
symbol: NSE trading symbol (e.g., "TCS", "RELIANCE") category: filter by type — "all" | "results" | "board_meeting" | "dividend" | "insider_trading" | "agm" | "acquisition" | "buyback" | "fund_raise" | "credit_rating" (CRISIL/ICRA/CARE/India Ratings actions — a debt-quality check) | "esg_rating" (ESG scores, which NSE files under "Credit Rating" too) days: how many days to look back (default 30; 730 for the rating categories, since rating actions come once or twice a year; max 3650)
An NSE failure is returned as an error (upstream_unavailable), never as an empty list — an empty list means NSE really has no such filings.
Examples: get_company_announcements("INFY", "results", 90) get_company_announcements("RELIANCE", "credit_rating") get_company_announcements("HDFCBANK", "dividend")
Inputs: symbol (required), days, category. Returns: object
get_company_overviewARead-only
Get a company's key ratios, current price, 52-week range, and about section.
data.price_freshness says when the price is from (price_as_of), whether it's an intraday print or the last close, the previous close and the day's change — so you can tell how current "current_price" is.
symbol: NSE/BSE symbol (e.g., "TCS", "INFY", "RELIANCE", "HDFCBANK") financial_type: "consolidated" (default) or "standalone"
This is the best starting point for any company analysis.
Inputs: symbol (required), financial_type. Returns: object
get_document_listARead-only
List all available annual reports and earnings call transcripts for a company.
Fetches from Screener.in company page and NSE API.
symbol: NSE/BSE symbol (e.g., "TCS", "INFY")
Use this to see which years/quarters ask_company_research can search. Annual reports are de-duplicated per year (a PDF is preferred over a .zip).
Inputs: symbol (required). Returns: object
get_financialsARead-only
Get financial statements for a company, as numbers (₹ Cr unless the label says % or days).
symbol: NSE/BSE symbol statement options: "profit_loss" — Revenue, expenses, operating profit, PAT (default). The trailing-twelve-months column comes back as data.ttm, separate from the fiscal years. "balance_sheet" — Assets, liabilities, equity, debt "cash_flow" — Operating, investing, financing cash flows "ratios" — Screener's ratios table (debtor/inventory/payable days, cash conversion cycle, working-capital days, ROCE) plus ROE %, debt-to-equity, and year-end P/E and P/B. data.row_sources says where each row comes from. financial_type: "consolidated" or "standalone" years: number of fiscal years (default 5, max 12) — TTM is never counted
Inputs: symbol (required), years, statement, financial_type. Returns: object
get_forward_outlookARead-only
Forward-looking inputs in one call, instead of extrapolating trailing data:
Analyst estimates — current and next fiscal-year EPS and revenue consensus (low/high, growth, analyst count) and forward P/E.
Order wins — NSE filings in the last
daysannouncing orders, contracts, LoAs, with rupee values stated in the headline summed.Capex & expansion — filings about new capacity, plants, commissioning.
Management guidance — the most relevant passages from the latest earnings call on guidance, order book / pipeline, and capex (needs the [ai] extra; otherwise returns an install hint).
Each part is independent — if one source is down the result is partial.
symbol: NSE/BSE symbol or company name days: filing look-back (30-730, default 180) include_earnings_call: set False to skip the transcript step (faster)
Inputs: symbol (required), days, include_earnings_call. Returns: object
get_full_analysisARead-only
Fetch ALL financial data for a company in a single call, as one report.
Uses the same windows as the standalone tools, so numbers always agree:
Key ratios, about, NSE/BSE codes
10 fiscal years of P&L (+ TTM), Balance Sheet, Cash Flow
Ratios history incl. ROE, debt-to-equity, year-end P/E and P/B
8 quarters of results
8 quarters of shareholding
Peer comparison table
Use this for a thorough analysis, to explain a company (including to a beginner), or to answer complex multi-part questions.
symbol: NSE/BSE symbol
Inputs: symbol (required), financial_type. Returns: object
get_insider_tradingARead-only
Recent insider trading disclosures (SEBI PIT Regulation 7(2)) for a company.
Shows promoter/KMP/designated-person trades — buy or sell, quantity,
value, and holding before/after — with no minimum trade size. This is
different from get_bulk_deals, which only catches single trades over
0.5% of equity and so misses most insider activity. Merges NSE's two PIT
feeds (each lists filings the other doesn't).
symbol: NSE trading symbol (e.g., "RELIANCE", "INFY") days: look-back window (default 365)
Examples: get_insider_trading("RELIANCE") get_insider_trading("ADANIENT")
Inputs: symbol (required), days. Returns: object
get_moat_signalsARead-only
Quantitative moat proxies for a company — market position plus how durable its economics have been.
Market position (from every listed company in its Screener industry): revenue share and rank by quarterly sales, industry concentration (HHI and CR4 — fragmented / moderately / highly concentrated), market-leader and top-3 flags. Durability (from up to ~12 years of statements): ROCE consistency (years ≥ 15%, median, min), operating-margin stability (standard deviation), sales CAGR, promoter-holding stability. Plus a signals summary with the thresholds used.
These are proxies — listed-company revenue share misses unlisted and imported competitors, and brand / switching costs / licences still need judgement (check the annual report and earnings calls).
symbol: NSE/BSE symbol or company name
Inputs: symbol (required). Returns: object
get_peer_comparisonBRead-only
Get peer comparison table as shown on Screener.in for a company.
Shows the company alongside its sector peers with key metrics like Market Cap, Sales, Net Profit, PE, ROCE, etc.
symbol: NSE/BSE symbol
Inputs: symbol (required), financial_type. Returns: object
get_portfolioARead-only
View your portfolio with live prices, P&L, and per-holding weight.
Fetches the current price for each holding from Screener.in and computes invested value, current value, gain/loss (₹ and %), and each position's weight in the total portfolio.
Examples: get_portfolio()
Inputs: no named parameters. Returns: object
get_quarterly_resultsBRead-only
Get the last 8 quarters of results for a company.
Shows: Revenue, Expenses, Operating Profit, OPM%, Net Profit, EPS Useful for identifying quarter-on-quarter growth trends and seasonality.
symbol: NSE/BSE symbol (e.g., "TCS", "WIPRO", "MARUTI")
Inputs: symbol (required), financial_type. Returns: object
get_recent_newsARead-only
Recent news headlines about a company (Google News, Indian edition).
Returns publisher, publish time (UTC) and link for each headline, newest first, de-duplicated. Use it for the "what's happened lately" context that financial statements can't show — results reactions, brokerage calls, management moves, price hikes, regulatory news. For the company's own exchange filings use get_company_announcements instead.
symbol: NSE/BSE symbol or company name days: look-back window (1-90, default 14) limit: max headlines (default 20)
Examples: get_recent_news("TMPV") get_recent_news("Garden Reach", days=30)
Inputs: symbol (required), days, limit. Returns: object
get_relative_valuationARead-only
Is this P/E cheap for its industry? Compares each stock's P/E and ROCE with the median of every listed company in its Screener industry, for up to 20 stocks in one call (stocks in the same industry share one fetch, so this scales across a screen's results).
Returns per stock: industry, P/E vs industry median (%), ROCE vs median (pp), and a one-line assessment (e.g. "at a premium to its industry, but the premium comes with clearly higher ROCE", or a possible value trap). Sorted cheapest-vs-industry first.
symbols: list (["HBLENGINE", "BSE", "TCS"]) or comma-separated string
Tip: screen_stocks(..., peer_relative=True) attaches the same data to screen results directly.
Inputs: symbols (required). Returns: object
notebook_aiADestructive
Save, read, and AI-summarize your investment research notes locally.
Notes are stored in ~/.screener-mcp/notebooks/ — persists across sessions.
action: "create" — new note (requires symbol + content) "append" — add to existing note (requires note_id + content) "read" — read a note (requires note_id) "list" — list all notes (optional symbol filter) "summarize" — AI-structured summary of all notes for a symbol "delete" — delete a note (requires note_id)
Examples: notebook_ai("create", symbol="TCS", content="Q3 results strong — revenue beat...") notebook_ai("append", note_id="a1b2c3d4", content="Met management — bullish on BFSI...") notebook_ai("list", symbol="TCS") notebook_ai("summarize", symbol="TCS") notebook_ai("read", note_id="a1b2c3d4")
Inputs: action (required), symbol, content, note_id. Returns: object
remove_portfolio_stockBDestructiveIdempotent
Remove a holding entirely from the portfolio (full exit).
Examples: remove_portfolio_stock("YESBANK")
Inputs: symbol (required). Returns: object
screen_by_themeARead-only
Run a pre-built thematic stock screen.
Query themes run a Screener query across the whole market. Sector themes
(defense, ev_theme, chemicals, railways, renewable_energy) start from the
companies actually in the sector — NSE index constituents, Screener
industry pages or a curated list — then apply the filters; the response's
data.universe says exactly which.
Themes and criteria:
undervalued_small_cap — Small caps (< ₹5000 Cr) with ROCE > 15%, low debt, P/E < 20
Market Capitalization < 5000 AND Return on capital employed > 15 AND Debt to equity < 0.5 AND Profit growth 3Years > 10 AND Price to Earning < 20
high_roce_low_debt — ROCE > 20%, debt-to-equity < 0.3, 5-year profit growth > 12%
Return on capital employed > 20 AND Debt to equity < 0.3 AND Profit growth 5Years > 12
compounders — 15%+ five-year sales and profit growth with ROE and ROCE > 15%, low debt
Sales growth 5Years > 15 AND Profit growth 5Years > 15 AND Return on equity > 15 AND Debt to equity < 0.5 AND Return on capital employed > 15
turnaround — Strong recent profit recovery on growing sales
Profit growth 3Years > 25 AND Profit growth last year > 20 AND Sales growth 3Years > 10 AND Return on capital employed > 10
rising_profit_falling_price — Profits up 15%+ a year over 3 years while the share price fell over the last year, P/E < 15
Profit growth 3Years > 15 AND Sales growth 3Years > 10 AND Return over 1year < 0 AND Price to Earning < 15
improving_roce — ROCE > 15% and higher than both last year's and its 5-year average
Return on capital employed > 15 AND Return on capital employed > Return on capital employed preceding year AND Return on capital employed > Average return on capital employed 5Years AND Debt to equity < 1
hidden_gems — Small cap (< ₹5000 Cr), ROCE > 15%, 5-year sales growth > 15%, low debt
Market Capitalization < 5000 AND Return on capital employed > 15 AND Sales growth 5Years > 15 AND Debt to equity < 0.5
dividend_aristocrats — Yield > 2%, a dividend paid in each of the last two years and a 3-year average payout > 20%, with ROE > 12% and low debt (Screener has no longer dividend-streak field)
Dividend yield > 2 AND Dividend last year > 0 AND Dividend preceding year > 0 AND Average dividend payout 3years > 20 AND Return on equity > 12 AND Debt to equity < 0.5
qarp — Quality at a reasonable price: P/E < 25, ROE > 15%, profit growth > 12%, low debt, > ₹1000 Cr
Price to Earning < 25 AND Return on equity > 15 AND Profit growth 5Years > 12 AND Debt to equity < 0.5 AND Market Capitalization > 1000
micro_cap_growth — Micro caps (< ₹1000 Cr) with 20%+ three-year sales and profit growth, ROCE > 15%
Market Capitalization < 1000 AND Sales growth 3Years > 20 AND Profit growth 3Years > 20 AND Return on capital employed > 15
defense — Defence companies (Nifty India Defence + Screener's Aerospace & Defense and Shipbuilding industries) with ROCE > 12%
sector universe; filters: Market Capitalization > 500 AND Return on capital employed > 12
ev_theme — Nifty EV & New Age Automotive constituents (EV makers, batteries, auto components) with ROCE > 12%
sector universe; filters: Market Capitalization > 1000 AND Return on capital employed > 12
chemicals — Specialty chemicals (Screener's Specialty Chemicals industry + Nifty Chemicals) with ROCE > 15%
sector universe; filters: Market Capitalization > 500 AND Return on capital employed > 15
railways — Railway companies (Screener's Railway Wagons industry + a curated list of railway PSUs and suppliers) with ROCE > 12%
sector universe; filters: Market Capitalization > 500 AND Return on capital employed > 12
renewable_energy — Renewable energy (curated list: wind/solar equipment makers and green power producers) with ROCE > 10%
sector universe; filters: Market Capitalization > 500 AND Return on capital employed > 10
limit: results per page (default 20)
page: 1-based page of results
Examples:
screen_by_theme("hidden_gems")
screen_by_theme("defense")
screen_by_theme("compounders", page=2)
Inputs: theme (required), page, limit. Returns: object
screen_stocksARead-only
Run a stock screen: Screener.in fundamental fields and/or technical (price-action) clauses, combined with AND, OR and parentheses.
Fundamental fields (Screener.in syntax, exact spelling matters): Market Capitalization, Current Price, Price to Earning, Price to book value, Return on capital employed, Return on equity, Debt to equity, Sales growth 5Years, Sales growth 3Years, Sales growth last year, Profit growth 5Years, Profit growth 3Years, Profit growth last year, Dividend yield, Pledged percentage, Net cash flow last year, Average return on equity 5Years, Average return on capital employed 5Years, Current ratio, EV / EBITDA, PEG Ratio
Technical clauses (evaluated from daily price history): 52 week low distance < 10 — % above the 52-week low 52 week high distance > 30 — % below the 52-week high RSI < 30 — 14-day RSI Price above 200 DMA — also: below, 20/50/200 DMA, "50 DMA above 200 DMA" Price vs 50 DMA < -5 — % above(+)/below(−) a DMA Volume vs 20 day average > 2 — today's volume ÷ 20-day average (spike detection)
Operators: > < >= <= =, combined with AND / OR and parentheses, e.g. "(Return on capital employed > 20 OR Return on equity > 25) AND Debt to equity < 0.5" "Return on capital employed > 15 AND (RSI < 30 OR 52 week low distance < 5)" Purely fundamental OR logic runs natively on Screener; when technical clauses sit under an OR, each alternative runs as its own screen (up to 6) and results are merged — each result lists matched_groups.
Result hygiene (on by default): min_market_cap: ₹ Cr floor added to the Screener query unless the query already has a Market Capitalization clause (0 = off) exclude_flagged: drop rows with implausible numbers (P/E < 1, >500% profit spike on a small base, profit > sales, negligible sales, sub-₹1 price) — they're listed in excluded_for_data_quality. False = keep them, flagged.
peer_relative: add each result's P/E and ROCE vs its industry median (first 20 results; slower — one industry fetch per industry).
How it runs: fundamental clauses go to Screener.in (login required);
technical clauses are then checked against up to max_candidates of those
matches. With only technical clauses, candidates come from a public NSE
index — universe (default "nifty500"; also nifty50, midcap100,
smallcap100, smallcap250, bank, it, auto, pharma, fmcg, metal, realty,
energy, defence, chemicals, ...) — so no login is needed.
sort_by: a technical metric (rsi14, pct_above_52w_low, volume_vs_20d_avg, ...) or a result column name. Default: the first technical filter.
page: 1-based page of results, limit per page (page=2 → results 26-50
with the default limit).
Returns partial=true (with a reason) if only some candidates could be checked — e.g. more fundamental matches than max_candidates.
Inputs: query (required), page, limit, order, +6 more. Returns: object
search_companyARead-only
Search for an Indian stock/company by name or NSE/BSE symbol.
Examples: search_company("Tata Consultancy") search_company("INFY") search_company("Jyothy Labs") search_company("ITC")
Inputs: query (required). Returns: object
search_market_commentaryARead-only
Semantic search for a question across MULTIPLE companies' already-indexed documents at once — e.g. "which of these companies mentioned raw material cost pressure in their recent earnings calls?"
Only searches documents already indexed via ask_company_research for each symbol — it does NOT download new documents, so cost/latency stays bounded no matter how many symbols are passed. Run ask_company_research(symbol, ...) first for any symbol you want included that hasn't been indexed yet.
Requires: pip install pdfplumber sentence-transformers chromadb
Examples: search_market_commentary("raw material cost pressure", ["TATASTEEL", "JSWSTEEL", "SAIL"]) search_market_commentary("management outlook on margins", ["ITC", "HINDUNILVR", "NESTLEIND"])
Inputs: symbols (required), question (required), top_k_per_symbol. Returns: object
update_portfolio_stockAIdempotent
Overwrite quantity and/or average price for an existing holding — e.g. after a partial sell (set the new remaining quantity) or to correct your recorded cost basis.
Use add_portfolio_stock instead for a new buy lot — it recalculates
the average price for you rather than replacing it.
symbol: NSE/BSE symbol already in your portfolio quantity: new total share count (0 = leave unchanged) avg_price: new average price (0 = leave unchanged)
Examples: update_portfolio_stock("RELIANCE", quantity=5) # sold half update_portfolio_stock("TCS", avg_price=3750) # correct cost basis
Inputs: symbol (required), quantity, avg_price. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 30 tools
Most tools have clearly distinct targets (screening, statements, shareholding, filings, deals, portfolio), and descriptions explicitly separate lookalikes such as get_bulk_deals vs get_insider_trading and get_recent_news vs get_company_announcements. The main fuzzy cluster is the comparison trio — get_peer_comparison (Screener's peer table), compare_companies (user-chosen 2-6 stocks) and get_relative_valuation (P/E & ROCE vs industry median) — plus get_52_week_low_candidates, which is largely a preset of screen_stocks with a technical clause.
Nearly everything is snake_case verb_noun: get_*, screen_*, search_*, compare_*, analyze_*, add/update/remove_portfolio_stock. The only real outlier is notebook_ai, a noun-named tool that multiplexes create/read/list/summarize/delete behind an action parameter, which breaks the one-verb-per-tool pattern used everywhere else.
30 tools is at the heavy end; the domain is genuinely broad (screening, company deep-dives, document Q&A, ownership/flows, commodities, portfolio, notes), so most tools earn a place and aggregates like get_full_analysis reduce chaining. Still, there is avoidable surface area: get_52_week_low_candidates duplicates screen_stocks, and the three comparison/valuation tools could be consolidated without losing capability.
Coverage is unusually thorough: discovery (search, thematic and custom screens), fundamentals plus 10-year statements, quarters, shareholding and pledge, peers, industry-relative valuation, moat proxies, forward-looking estimates/order wins/capex, news and analyst targets, filings, bulk and insider deals, commodities, document indexing/Q&A, and a full portfolio CRUD plus notes lifecycle. No obvious dead ends for a stock-research workflow.
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.
Your investing research inside Claude: watchlists, financial ratios, reverse-DCF valuations, investment theses, notes, portfolio, earnings calendar and news for the companies you follow. 70 read and write tools; ask what's on your morning desk, rank a watchlist by ROE, log a trade or save a thesis. OAuth sign-in. Free to start.
48 tools for ~8,000 NSE & BSE stocks: quotes, screener, financials, filings, FII/DII, options
Indian stock market data: NSE/BSE prices, financials, NIFTY/SENSEX, mutual funds, screener.
Related MCP Servers
- FlicenseAqualityDmaintenanceProvides financial data for Indian listed companies from screener.in, enabling users to search companies and fetch financial statements, ratios, and peer comparisons.22-
- AlicenseNot gradedqualityDmaintenanceAI equity-research analyst for Indian NSE/BSE markets with 28 MCP tools enabling sector screens, valuations, SWOTs, and forensic audits using Claude Agent SDK.Apache 2.0
- 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 through 55 tools covering live quotes, financials, technicals, a 326-ratio screener, FII/DII flows, option chains and IV, corporate filings, IPOs, bulk deals and portfolio P&L. It can be used remotely over OAuth or locally via npx/uvx from Claude, ChatGPT, Cursor, VS Code, Codex and Gemini CLI.-