screener-mcp

screener-mcp — Indian Stock Research for Claude

Turn Claude into a personal Indian equity analyst powered by liveScreener.indata — now with AI document analysis, NSE announcements, and research notebooks.

300+ active users·Report an issue·LinkedIn·logeshl2003@gmail.com

"Compare ITC and HUL on all key ratios" "Find chemical stocks with low debt and strong growth" "Explain Jyothy Labs like I'm a beginner" "What are the red flags in Asian Paints?" "Find hidden gems below ₹5000 crore market cap" "What did TCS management say about margins in Q3FY25?" "Summarize the key risks from Reliance's 2024 annual report" "Show me recent dividend announcements for HDFCBANK" "How does copper price affect Havells and Polycab?" "Save a research note on TITAN — strong Q3, watch margins"

claude mcp add screener -s user -- uvx screener-mcp

Requiresuv:pip install uvorbrew install uv

git clone https://github.com/LogeshR15/screener-mcp cd screener-mcp python3.11 -m venv .venv source .venv/bin/activate pip install -e . claude mcp add screener -s user -- \ $(pwd)/.venv/bin/python3.11 \ $(pwd)/run_server.py

1.Register free atscreener.in/register

export SCREENER_USERNAME="your@email.com" export SCREENER_PASSWORD="yourpassword"

pip install pdfplumber sentence-transformers chromadb # or: pip install -e ".[ai]"

claude mcp list # screener stdio Connected

Then ask Claude:"Search for Asian Paints"— you should get results.

Uses a local RAG pipeline: PDF → pdfplumber → ChromaDB → sentence-transformers. Results are cached on disk — the same report is never re-downloaded or re-indexed.

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

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

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-processed twice.

screener-mcp/ ├── run_server.py └── src/screener_mcp/ ├── server.py # FastMCP — all 21 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 ├── shareholders.py # Bulk deal / shareholder search ├── commodities.py # Commodity price analysis └── notebook.py # Research notes

- 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
- This is a research tool — not financial advice

SeeCONTRIBUTING.md— adding a new tool takes ~10 minutes.

Logesh Ramasamy·logeshl2003@gmail.com·LinkedIn

SEC filings, earnings transcripts, guidance signals & macro calendar for S&P 500. 11 MCP tools for algo traders and financial analysts using Claude Code.