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 · [email protected]

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

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 analyze_annual_report, analyze_earnings_call, ask_company_research, and search_market_commentary. Without it, those four 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"
"List the pre-built screening themes"

If these return real data, the server is working end to end.

What it provides

Company research — financials, ratios, shareholding, peer comparison, red-flag detection (no login required)
Stock screening — custom Screener.in-style queries and pre-built thematic screens (requires a free Screener.in login)
Document analysis — ask questions over annual reports and earnings call transcripts using a local RAG pipeline
Corporate events — NSE announcements, bulk deals, insider trading disclosures, promoter pledge trends, credit ratings
Market & research — commodity price context, local research notes
Portfolio — a private, local holdings tracker with live P&L

31 tools in total — full reference below.

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
Read an annual report — "What are the key risks in Reliance's 2024 annual report?" → analyze_annual_report
Read an earnings call — "What did TCS say about margins in Q3FY25?" → analyze_earnings_call
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
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)
        ├──► NSE India     (announcements, bulk deals, filings)
        └──► MCX India     (commodity prices)
        │
        ▼
  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

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": "[email protected]",
        "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 31 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 (`screen_stocks`, `screen_by_theme`)	Yes
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="[email protected]"
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": "[email protected]",
  "SCREENER_PASSWORD": "yourpassword"
}

Never commit real credentials — the values above are placeholders.

Tools — 31 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, about	No
`get_financials`	P&L / Balance Sheet / Cash Flow / Ratios	No
`get_quarterly_results`	Last 8 quarters of results	No
`get_shareholding_pattern`	Promoter / FII / DII holding trend	No
`get_peer_comparison`	Sector peer comparison table	No
`compare_companies`	Side-by-side comparison (2–5 stocks)	No
`compare_stocks_ui`	Interactive dashboard (Claude Desktop)	No
`get_full_analysis`	All data combined for deep analysis	No
`analyze_red_flags`	Structured red flag detection	No
`explain_for_beginners`	Plain-language company explainer	No

Stock Screening

Tool	What it does	Login needed
`screen_stocks`	Custom Screener.in query	Yes
`screen_by_theme`	Pre-built thematic screens	Yes
`list_investment_themes`	Show all available themes	No

Document Analysis

Tool	What it does	Extra deps needed
`get_document_list`	List annual reports & earnings call transcripts	No
`analyze_annual_report`	Ask any question over one annual report PDF	Yes
`analyze_earnings_call`	Ask any question over one earnings call transcript	Yes
`ask_company_research`	Ask a question across ALL of a company's cached documents at once (multiple years/quarters)	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 recent documents and searches across them together (good for "how has X changed over time?"); 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	No
`search_shareholder`	Find investor activity via NSE bulk deals	No
`get_bulk_deals`	All NSE bulk deals for one company — no investor name needed	No
`get_insider_trading`	SEBI PIT promoter/KMP/designated-person trade disclosures, no size threshold	No
`get_promoter_pledge_history`	Dedicated promoter pledge % trend with severity flag	No
`get_credit_ratings`	CRISIL/ICRA/CARE/India Ratings rating actions — a debt-quality check	No

Market & Research

Tool	What it does	Login needed
`get_commodity_prices`	Commodity price context + impacted companies	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:

analyze_annual_report("TCS", 2024, "What are the key risks?")

  1. Fetch PDF link from Screener.in / NSE
  2. Download and parse with pdfplumber
  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 returns top-5 relevant excerpts
  7. Claude reasons over the excerpts to answer your question

Results are cached — the same report is never re-downloaded or re-processed.

Stock screening

Pre-built themes

undervalued_small_cap       Small caps, ROCE > 15%, low debt, PE < 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 Improving profits, compressed valuation
improving_roce              ROCE > 15% with profit momentum
hidden_gems                 Small cap, high ROCE, strong growth
dividend_aristocrats        Consistent dividends with quality financials
qarp                        Quality at reasonable price
micro_cap_growth            High-growth micro caps < ₹1000 Cr
ev_theme                    EV & auto ancillary growth companies
chemicals                   Specialty chemicals, strong fundamentals
defense                     Defense sector with revenue momentum
railways                    Railway infra/equipment companies
renewable_energy            Renewable energy sector

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: > < = AND

Full field list in CONTRIBUTING.md.

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)	`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 [email protected] \
  -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
MCX India	Commodity prices (best-effort)

Financial data lags by ~1 quarter
Document analysis requires machine-readable PDFs (scanned/image-only PDFs may fail)
NSE bulk deals only capture single trades > 0.5% of equity
get_company_announcements and search_shareholder depend on NSE's public API, which frequently rate-limits or blocks server IPs (403/404 responses) — if a query returns "no data found", it may be NSE blocking the request rather than an empty result
This is a research tool — not financial advice

Project layout

screener-mcp/
├── run_server.py
├── tests/                          # Offline registry + docs-consistency tests
└── src/screener_mcp/
    ├── server.py                   # FastMCP — all 31 tool definitions
    ├── client.py                   # Screener.in HTTP client + auth
    ├── core/
    │   ├── nse_client.py           # NSE India API (announcements, filings)
    │   ├── 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
    └── tools/
        ├── company_tools.py        # Company data tools
        ├── screening_tools.py      # Stock screening + themes
        ├── analysis_tools.py       # Deep analysis, red flags, beginner
        ├── documents.py            # Annual reports + earnings calls (RAG)
        ├── announcements.py        # NSE corporate announcements + credit ratings
        ├── shareholders.py         # Bulk deal / shareholder search
        ├── insider_trading.py      # SEBI PIT insider trading disclosures
        ├── 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

Contact

Logesh Ramasamy · [email protected] · LinkedIn

screener-mcp

screener-mcp

What you can do

Quick start

Verify it works

What it provides

Example workflows

Architecture

Installation options

Recommended

Claude Code

Claude Desktop

pip / PyPI

Developer (local clone)

Advanced: HTTP and Docker

Credentials

Tools — 31 total

Company Research

Stock Screening

Document Analysis

Corporate Events

Market & Research

Portfolio

Document analysis

Stock screening

Pre-built themes

Custom screen syntax

Remote HTTP server

Docker

Data sources & limitations

Project layout

Contributing

License

Contact

Yorumlar (0)