Skip to main content
Glama
screener-mcp
by LogeshR15

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.

PyPI Python CI License: MIT

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-mcp

This 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-mcp

Core vs. [ai]: the base package covers company data, screening, NSE announcements, and portfolio tracking. The [ai] extra adds pdfplumber, chromadb, and sentence-transformers (~1–2GB, via torch) to power ask_company_research and search_market_commentary (and the management-guidance part of get_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  Connected

Then 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't

  • Price-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_companies

  • Screen for opportunities — "Find low-debt, high-ROCE small caps" → screen_by_theme or screen_stocks

  • Find pullbacks — "High-ROCE, low-debt stocks near their 52-week low" → get_52_week_low_candidates, or screen_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_sector

  • What the Street thinks — "Analyst targets and recent news for TMPV" → get_analyst_targets, get_recent_news

  • Is it cheap for its sector? — "Which of these 15 stocks trade below their industry P/E?" → get_relative_valuation, or screen_stocks(..., peer_relative=True)

  • Moat check — "Is MSUMI a market leader with durable returns?" → get_moat_signals

  • Future growth — "What's the order pipeline and guidance for BEL?" → get_forward_outlook

  • Read 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_flags

  • Track NSE activity — "Show recent announcements for HDFCBANK" → get_company_announcements

  • Research 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_stock

  • Save 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 answers

screener-mcp fetches and normalizes the data; Claude does the analysis and explains it in plain language.


Installation options

# 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-mcp

Claude 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.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.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 ENOENT on launch? Claude Desktop starts with a minimal PATH. Run which uvx and 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 analysis

Then 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.py

Any Python 3.11+ works — e.g. python3.12 -m venv .venv — just point claude mcp add at that interpreter. pip install -e . failing with "editable mode currently requires a setuptools-based build"? Upgrade pip in 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 (screen_stocks, screen_by_theme)

Yes

Technical-only screens, get_52_week_low_candidates, compare_to_sector

No (a login lets get_52_week_low_candidates scan the whole market instead of an index)

get_relative_valuation, get_moat_signals, get_forward_outlook, get_analyst_targets, get_recent_news

No (get_forward_outlook's earnings-call guidance needs the [ai] extra)

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

search_company

Find company by name or symbol

No

get_company_overview

Key ratios, price, 52W range, NSE/BSE codes, about, Screener's pros/cons

No

get_financials

P&L (TTM separate) / Balance Sheet / Cash Flow / Ratios incl. year-end P/E, P/B, ROE, debt-to-equity

No

get_quarterly_results

Last 8 quarters of results

No

get_shareholding_pattern

8-quarter holding trends per category, promoter-group detection, promoter pledge

No

get_peer_comparison

Sector peer comparison table

No

compare_companies

2–6 stocks side by side, with point-in-time red flags; interactive dashboard (MCP App) where supported, JSON everywhere

No

get_full_analysis

All data combined for deep analysis (same windows as the standalone tools)

No

analyze_red_flags

Rule-based red-flag checks over the full history, each with evidence and thresholds

No

Stock Screening

Tool

What it does

Login needed

screen_stocks

Screener.in query plus technical clauses (52W distance, RSI, DMA, volume spike)

Fundamental clauses only

get_52_week_low_candidates

Quality filters + proximity to 52-week low, with overview fields per match

No

get_relative_valuation

P/E and ROCE vs the industry median for up to 20 stocks at once

No

compare_to_sector

Stock's return vs its sector index and Nifty 50, with a market-vs-company verdict

No

screen_by_theme

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

get_document_list

List annual reports & earnings call transcripts

No

ask_company_research

Ask a question over a company's annual reports and earnings calls — all recent ones, one doc_type, or one document (year / quarter / pdf_url)

Yes

search_market_commentary

Search a question across multiple companies' already-indexed documents at once

Yes

ask_company_research and search_market_commentary build 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

get_company_announcements

NSE corporate announcements with category filter — incl. credit_rating (CRISIL/ICRA/CARE/India Ratings) and esg_rating

No

get_bulk_deals

NSE bulk deals by company (symbol), by investor (name), or both

No

get_insider_trading

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

get_recent_news

Recent news headlines for a company (Google News), newest first

No

get_analyst_targets

Consensus target price (mean/median/high/low, analyst count, rating split) + broker targets in recent headlines

No

get_forward_outlook

Analyst EPS/revenue estimates, order wins and capex filings, management guidance from the latest earnings call

No ([ai] for guidance)

get_moat_signals

Revenue share/rank and industry concentration (HHI), plus ROCE, margin and promoter-holding durability

No

get_commodity_prices

International benchmark price, period moves, ≈INR price + exposed companies' symbols (incl. wheat; tobacco and wood pulp as exposure-only)

No

notebook_ai

Save, read, and AI-summarize research notes locally

No

Portfolio

Tool

What it does

Login needed

add_portfolio_stock

Add/merge a holding into your local portfolio (quantity-weighted avg cost)

No

update_portfolio_stock

Overwrite quantity/avg price on an existing holding (partial sell, cost correction)

No

remove_portfolio_stock

Remove a holding entirely

No

get_portfolio

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 page

Results 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 Cr

Sector 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 producers

Every 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 < 5

Supported 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 volume
Return 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 a Market Capitalization clause. Set it to 0 to turn it off.

  • exclude_flagged drops rows with implausible numbers and lists them under excluded_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 to False to keep these rows, marked with data_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_fields with status: "partial", and their values are null, never "" or 0.

  • Companies without subsidiaries have a blank /consolidated/ page on Screener. The server falls back to standalone figures and says so in warnings.

  • Non-canonical symbols like MOTHERSONWIR resolve through Screener search. A confident match proceeds and is recorded in meta.interpreted_as. An ambiguous one returns error.candidates (top 3), so you can retry in one call.

  • Errors are flagged on the wire. When status is "error", the MCP result also has isError: 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/mcp

Env vars:

Variable

Purpose

Default

SCREENER_USERNAME

Screener.in login email (needed for screening tools)

—

SCREENER_PASSWORD

Screener.in password

—

MCP_TRANSPORT

stdio or streamable-http

stdio

PORT / MCP_PORT

Port to listen on (HTTP transport only)

8000

MCP_HOST

Bind address (HTTP transport only)

127.0.0.1 (the Docker image sets 0.0.0.0)

CHROMA_PERSIST_DIR

Where the document-analysis vector store is cached

~/.screener-mcp/chroma_db

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-http server 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 set SCREENER_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:latest

Then point the client at http://<host>:8000/mcp.


Data sources & limitations

Source

Data provided

Screener.in

10+ years of financials, ratios, shareholding, peers

NSE India

Announcements, annual reports, bulk deals, insider trading disclosures

Yahoo Finance

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. Set SCREENER_PRICE_CACHE=0 to disable the cache

  • Commodity 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 partial

  • get_company_overview returns data.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 stale

  • Analyst 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 returns status: "error" with error.type: "upstream_unavailable". When only some bulk-deal days fail, it returns partial. An empty list with status: "ok" means NSE really had no rows. These tools resolve fuzzy symbols the same way as the Screener tools, and they return a not_on_nse error 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 tracker

Contributing

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]"
pytest

The 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 analysis

  • requirements.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 tools
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)

Inputs: symbol (required), quantity (required), avg_price (required). Returns: object

analyze_red_flagsA
Read-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_researchA
Read-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_companiesA
Read-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_sectorA
Read-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_candidatesA
Read-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_targetsA
Read-only

Analyst price targets for a stock, from two independent sources:

  1. 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.

  2. 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_dealsA
Read-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_pricesA
Read-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_announcementsA
Read-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_overviewA
Read-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_listA
Read-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_financialsA
Read-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_outlookA
Read-only

Forward-looking inputs in one call, instead of extrapolating trailing data:

  1. Analyst estimates — current and next fiscal-year EPS and revenue consensus (low/high, growth, analyst count) and forward P/E.

  2. Order wins — NSE filings in the last days announcing orders, contracts, LoAs, with rupee values stated in the headline summed.

  3. Capex & expansion — filings about new capacity, plants, commissioning.

  4. 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_analysisA
Read-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_tradingA
Read-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_signalsA
Read-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_comparisonB
Read-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_portfolioA
Read-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_resultsB
Read-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_newsA
Read-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_valuationA
Read-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

get_shareholding_patternA
Read-only

Shareholding pattern for the last 8 quarters, with the analysis:

  • rows: Promoter / FII / DII / Government / Public %, shareholder count

  • trends: per category — latest %, change over the window and over the last quarter (pp), direction

  • promoter_group: present or not. Companies like ITC have no promoter; promoter-trend and pledge checks then don't apply, and the response says so instead of implying "no pledge".

  • pledge: % of promoter holding pledged, from Screener's analysis, with severity (>50% high, 20-50% moderate, >0-20% low); not_flagged (none flagged — small pledges may not be); or not_applicable (no promoter)

symbol: NSE/BSE symbol

Examples: get_shareholding_pattern("ZEEL") get_shareholding_pattern("ITC")

Inputs: symbol (required). Returns: object

notebook_aiA
Destructive

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_stockB
DestructiveIdempotent

Remove a holding entirely from the portfolio (full exit).

Examples: remove_portfolio_stock("YESBANK")

Inputs: symbol (required). Returns: object

screen_by_themeA
Read-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_stocksA
Read-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_companyA
Read-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_commentaryA
Read-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_stockA
Idempotent

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

    A3.8/5.0

    Scored across 30 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness5/5

    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

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Provides financial data for Indian listed companies from screener.in, enabling users to search companies and fetch financial statements, ratios, and peer comparisons.
      2
      2
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      AI 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
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to search, screen, and analyze 8,200+ NSE and BSE listed securities through 55 tools covering live quotes, financials, technical indicators, FII/DII flows, option chains, filings, IPOs, bulk deals, and portfolio P&L.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to search, screen and analyze all 8,200+ NSE and BSE listed stocks 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.
      -