screener-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PORT | No | Port to listen on (HTTP transport only). | 8000 |
| MCP_HOST | No | Bind address (HTTP transport only). The Docker image sets 0.0.0.0. | 127.0.0.1 |
| MCP_PORT | No | Alternative port variable to listen on (HTTP transport only). | 8000 |
| MCP_TRANSPORT | No | Transport mode: 'stdio' or 'streamable-http'. | stdio |
| SCREENER_PASSWORD | No | Screener.in password, used together with SCREENER_USERNAME for the screening tools. | |
| SCREENER_USERNAME | No | Screener.in login email. Needed for the screening tools with fundamental clauses; other tools work without a login. | |
| CHROMA_PERSIST_DIR | No | Where the document-analysis vector store is cached. | ~/.screener-mcp/chroma_db |
| SCREENER_PRICE_CACHE | No | Set to 0 to disable the local price-history cache at ~/.screener-mcp/price_cache. | |
| SCREENER_MIN_INTERVAL | No | Minimum interval in seconds between Screener.in requests (request pacing). | 0.25 |
| SCREENER_MAX_CONCURRENCY | No | Maximum number of concurrent Screener.in requests. | 3 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
You are an expert Indian equity analyst with deep knowledge of Indian stock markets, Screener.in data, and long-term investing principles.
When users ask about stocks, companies, or investment themes:
Use the appropriate tools to fetch real Screener.in data
Reason over the data like a seasoned analyst
Present findings clearly — use tables, bullet points, and plain language
Always contextualize numbers (e.g., "ROCE of 25% is excellent — above industry average")
Flag important caveats (data is point-in-time, past performance ≠ future results)
For beginners, translate jargon into everyday language
For advanced users, go deeper into trends and red flags
You have access to all financial statements, ratios, shareholding data, and screening capabilities. The data comes from Screener.in and covers BSE/NSE listed Indian companies.
Always be honest about limitations: Screener data may lag by a quarter, sector classifications are broad, and you cannot predict stock prices.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| search_companyA | 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") |
| screen_stocksA | 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 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, Returns partial=true (with a reason) if only some candidates could be checked — e.g. more fundamental matches than max_candidates. |
| get_relative_valuationA | 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. |
| get_moat_signalsA | 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 |
| get_forward_outlookA | Forward-looking inputs in one call, instead of extrapolating trailing data:
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) |
| get_52_week_low_candidatesA | 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 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) |
| compare_to_sectorA | 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 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") |
| get_recent_newsA | 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) |
| get_analyst_targetsA | Analyst price targets for a stock, from two independent sources:
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") |
| screen_by_themeA | |
| get_company_overviewA | 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. |
| get_financialsA | 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 |
| get_quarterly_resultsB | 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") |
| get_shareholding_patternA | Shareholding pattern for the last 8 quarters, with the analysis:
symbol: NSE/BSE symbol Examples: get_shareholding_pattern("ZEEL") get_shareholding_pattern("ITC") |
| get_peer_comparisonB | 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 |
| compare_companiesA | 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") |
| get_full_analysisA | 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:
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 |
| analyze_red_flagsA | Rule-based red-flag checks over a company's full history — computed here, each flag with its severity and the numbers behind it:
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 |
| get_document_listA | 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). |
| ask_company_researchA | 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]' |
| search_market_commentaryA | 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"]) |
| get_company_announcementsA | 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") |
| get_bulk_dealsA | 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") |
| get_insider_tradingA | 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 symbol: NSE trading symbol (e.g., "RELIANCE", "INFY") days: look-back window (default 365) Examples: get_insider_trading("RELIANCE") get_insider_trading("ADANIENT") |
| get_commodity_pricesA | 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 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") |
| notebook_aiA | 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") |
| add_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) |
| update_portfolio_stockA | 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 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 |
| remove_portfolio_stockB | Remove a holding entirely from the portfolio (full exit). Examples: remove_portfolio_stock("YESBANK") |
| get_portfolioA | 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() |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| deep_dive | Full fundamental deep dive on one company, ending in a verdict with risks. |
| value_screen | Find quality companies at reasonable valuations and shortlist the best few. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| analyst_guide | How to use the Screener Stock Research assistant. |
| query_syntax_guide | Screener.in query language reference for stock screening. |
| Stock Comparison Dashboard | Interactive dashboard rendered for compare_companies results. |
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.