Skip to main content
Glama
shivamg194-lab

screener-mcp-server

by shivamg194-lab
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Remote

screener-mcp-server

An MCP server for Screener.in — search Indian listed companies, pull key ratios, multi-year financial statements, peer comparisons, and run custom fundamental screens, all from Claude (or any MCP client).

Important: no official API

Screener.in explicitly states they don't provide an API — only CSV export from the UI. This server works by reading the same public, signed-out pages a browser would see (search, company pages, and the /screen/raw/ query endpoint). It does not require login for the core tools.

Because this isn't an official API:

  • Please keep request volume reasonable — the server throttles and caches requests for you (5 min cache, ~600ms min gap between requests), don't work around that.

  • Guest (logged-out) access to custom screens is capped by Screener to a small number of result rows. If you want more rows or CSV-export-only data, set SCREENER_SESSION_COOKIE (see below) to a cookie from your own logged-in session.

  • Screener's HTML structure can change without notice; if a tool starts erroring, the CSS selectors in src/services/scraper.ts likely need a small update.

  • Review Screener's Terms before heavy or commercial use.

Related MCP server: sfinance-mcp-server

Tools

Tool

What it does

screener_search_companies

Look up a company's Screener ID/URL by name or ticker

screener_get_company_overview

Key ratios (Market Cap, P/E, ROE, ROCE, etc.), About text, Pros/Cons

screener_get_financial_statement

Quarterly results, P&L, balance sheet, cash flow, or ratios — multi-year table

screener_get_peer_comparison

The peer-comparison table shown on a company's page

screener_run_custom_screen

Run a Screener query-builder screen (e.g. Market Capitalization > 500 AND Return on equity > 22) across the whole market

technical_get_indicator

RSI, SMA, EMA, or MACD for an NSE/BSE stock, via Alpha Vantage

Why compute indicators ourselves instead of using Groww or Alpha Vantage?

  • Groww's official MCP (mcp.groww.in) is account-linked via OAuth (it's built to read your portfolio/trades). Folding it into this server would mean building a full OAuth pass-through proxy — a much bigger project, and unnecessary for public technicals like RSI.

  • Alpha Vantage's NSE/BSE coverage (NSE:TICKER format) turned out to be unreliable in practice — it often only returns NASDAQ data despite documentation claiming Indian exchange support.

Instead, technical_get_indicator pulls raw historical close prices from Yahoo Finance's public chart endpoint (ticker + .NS/.BO suffix — the same data source most community NSE tooling, like yfinance, relies on) and computes RSI (Wilder's method), SMA, EMA, and MACD (12/26/9) server-side using standard formulas. No API key, no OAuth, no external rate limits — just one more tool in the same connector.

Since this is an unofficial-but-widely-used endpoint (not a documented Yahoo API), if it ever breaks, check src/services/yahoo.ts — the fix is usually just adjusting the URL or response shape to match Yahoo's current chart endpoint.

Setup

npm install
npm run build

Run locally (stdio) — for Claude Desktop / Claude Code

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "screener": {
      "command": "node",
      "args": ["/absolute/path/to/screener-mcp-server/dist/index.js"]
    }
  }
}

Run as a remote HTTP server

TRANSPORT=http PORT=3000 npm start

Then point your MCP client at http://localhost:3000/mcp.

Optional: logged-in session for more screen results

export SCREENER_SESSION_COOKIE="csrftoken=...; sessionid=..."

Grab this from your browser's DevTools → Network tab → any request to screener.in → Cookie request header, while logged into your own Screener account. Never share this value; it's your personal session.

Development

npm run dev    # tsc --watch

If Screener changes their page markup and a tool starts failing, check the selectors in src/services/scraper.ts (#top-ratios, .pros/.cons, #profit-loss/#balance-sheet/etc. table sections, #peers table) against the current HTML.

Available Tools

5 tools
screener_get_company_overviewGet Company Overview from Screener.inA
Read-onlyIdempotent

Fetch a company's snapshot from its Screener.in page: key ratios (Market Cap, Current Price, Stock P/E, Book Value, Dividend Yield, ROCE, ROE, Face Value, etc.), a short "About" description, and Screener's machine-generated Pros/Cons list.

This does NOT include multi-year financial statements — use screener_get_financial_statement for those, or screener_get_peer_comparison for peer benchmarking.

Args:

  • identifier (string): Ticker (e.g. "TCS"), company name (e.g. "Tata Consultancy Services"), or a screener.in company URL/path. If unsure of the exact match, call screener_search_companies first.

  • consolidated (boolean, default true): Consolidated (with subsidiaries) vs standalone financials.

Returns: JSON: { "name": string, "screenerUrl": string, "aboutText": string|null, "topRatios": [{name, value}], "pros": string[], "cons": string[] }

Examples:

  • Use when: "What's TCS's current P/E and ROE?" -> identifier="TCS"

  • Don't use when: You need 10 years of quarterly revenue (use screener_get_financial_statement instead)

Error Handling:

  • Returns an error if no matching company is found — try screener_search_companies to confirm the right name/ticker first.

ParametersJSON Schema
NameRequiredDescriptionDefault
identifierYesCompany ticker (e.g. 'TCS', 'INFY'), company name (e.g. 'Tata Consultancy Services'), or a full/relative screener.in company URL/path.
consolidatedNoUse consolidated financials (includes subsidiaries) if true, standalone (parent company only) if false. Default: true.

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=True, idempotentHint=True. Description adds behavioral details like error handling (returns error if no match found), which is useful beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with sections (description, args, returns, examples, error handling). Every sentence provides value; no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, description specifies return format as JSON with fields. Covers error handling and prerequisites. Complete for a simple read-only tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so schema already documents both parameters. Description's Args section restates schema info without adding significant new meaning, meeting baseline expectation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool fetches a company snapshot including key ratios, about description, pros/cons. Explicitly distinguishes from siblings by listing what it does NOT include (financial statements, peer comparison).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use (e.g., 'What is TCS's current P/E?') and when-not-to-use (e.g., need multi-year statements, use screener_get_financial_statement). Also suggests using screener_search_companies if unsure of identifier.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

screener_get_financial_statementGet Financial Statement from Screener.inA
Read-onlyIdempotent

Fetch a multi-period financial statement table for a company from Screener.in: quarterly results, annual profit & loss, balance sheet, cash flow, or per-year efficiency ratios.

Args:

  • identifier (string): Ticker, company name, or screener.in URL/path.

  • statement (enum): One of "quarters", "profit-loss", "balance-sheet", "cash-flow", "ratios".

  • consolidated (boolean, default true): Consolidated vs standalone.

Returns: JSON: { "section": string, "periods": string[], "rows": [{ "label": string, "values": string[] }] } Each row's values align positionally with "periods".

Examples:

  • Use when: "Show me TCS's last few years of profit & loss" -> identifier="TCS", statement="profit-loss"

  • Use when: "What's Infosys's debtor days trend?" -> identifier="INFY", statement="ratios"

  • Don't use when: You just want current P/E or market cap (use screener_get_company_overview)

Error Handling:

  • Returns an error if the statement section isn't present for that company (e.g. some companies don't report all statements) or if the company can't be found.

ParametersJSON Schema
NameRequiredDescriptionDefault
statementYesWhich financial statement/table to retrieve: 'quarters' (quarterly results), 'profit-loss' (annual P&L), 'balance-sheet', 'cash-flow', or 'ratios' (per-year efficiency ratios like debtor days, ROCE%).
identifierYesCompany ticker (e.g. 'TCS', 'INFY'), company name (e.g. 'Tata Consultancy Services'), or a full/relative screener.in company URL/path.
consolidatedNoUse consolidated financials (includes subsidiaries) if true, standalone (parent company only) if false. Default: true.

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: it returns a multi-period table with a specific JSON structure, and explains error cases (statement section not present, company not found). This goes beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections: purpose, Args, Returns, Examples, Error Handling. Every sentence serves a purpose, and it is front-loaded with the most important information. No redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (3 parameters, multi-period tabular return data, no output schema), the description is thorough. It covers input semantics, output structure (section, periods, rows), examples, and error handling. No gaps remain for a typical use case.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description's Args section restates parameter meanings with examples, but the schema already has detailed descriptions for each property. It adds modest value by showing how parameters are used in queries.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches multi-period financial statement tables from Screener.in, listing five specific statement types. It distinguishes from siblings by explicitly saying when not to use it (for current P/E or market cap, use screener_get_company_overview).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit examples for when to use the tool with realistic queries ('Show me TCS's profit & loss' → identifier='TCS', statement='profit-loss') and when not to ('Don't use when: You just want current P/E or market cap'). Also notes error handling for missing statements.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

screener_get_peer_comparisonGet Peer Comparison from Screener.inA
Read-onlyIdempotent

Fetch the peer-comparison table Screener.in shows on a company's page — the same industry peers, compared on CMP, P/E, market cap, ROE, and other columns Screener selects.

Args:

  • identifier (string): Ticker, company name, or screener.in URL/path.

  • consolidated (boolean, default true): Consolidated vs standalone.

Returns: JSON: { "columns": string[], "peers": [{ "name": string, "values": { [column]: string } }] }

Examples:

  • Use when: "How does TCS compare to its industry peers on P/E and ROE?" -> identifier="TCS"

  • Don't use when: You want a custom peer set with your own filter criteria (use screener_run_custom_screen instead)

Error Handling:

  • Returns an error if no peer table is found for the company (uncommon, but can happen for delisted or very niche companies).

ParametersJSON Schema
NameRequiredDescriptionDefault
identifierYesCompany ticker (e.g. 'TCS', 'INFY'), company name (e.g. 'Tata Consultancy Services'), or a full/relative screener.in company URL/path.
consolidatedNoUse consolidated financials (includes subsidiaries) if true, standalone (parent company only) if false. Default: true.

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark as readOnly and idempotent. The description adds the return JSON structure, error handling for missing peer tables, and confirms it replicates the website's table. No contradictions; adds valuable context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (purpose, args, returns, examples, error handling). Every sentence contributes useful information without redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter tool with no output schema, the description provides a full picture: input types, return format (including structure), usage examples, and an error case. This is sufficient for an AI agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed descriptions for both parameters (identifier and consolidated). The description's Args section merely repeats the schema's information without adding new semantic meaning, so it meets the baseline but doesn't exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches the peer-comparison table from Screener.in, specifying it returns industry peers and typical columns. It distinguishes itself from siblings like screener_run_custom_screen by noting this uses Screener's default peer set.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The 'Examples' section provides explicit use-cases: when to use (comparing a company to peers) and when not to use (custom peer set), even naming the alternative tool (screener_run_custom_screen). This is exemplary guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

screener_run_custom_screenRun a Custom Stock Screen on Screener.inA
Read-onlyIdempotent

Run a custom stock screen using Screener.in's query-builder syntax against 10+ years of financial data for all listed Indian companies, and return the matching companies.

This is the core "screener" feature — filter the whole market by fundamental criteria in one call, instead of checking companies one by one.

Args:

  • query (string): Screener query syntax. Combine conditions with AND/OR. Examples: "Market Capitalization > 500 AND Return on capital employed > 22" "Price to Earning < 15 AND Debt to equity < 0.5 AND Sales growth 3Years > 10" Common fields: Market Capitalization, Current Price, Price to Earning, Return on equity, Return on capital employed, Debt to equity, Sales growth, Profit growth, Dividend yield, Book value, Promoter holding.

  • limit (number, 1-100, default 25): Max rows to return. Note: without a logged-in session (SCREENER_SESSION_COOKIE env var), Screener itself caps guest results to a small number regardless of this limit.

Returns: JSON: { "columns": string[], "rows": [{name, values}], "totalFound": number|null, "truncated": boolean }

Examples:

  • Use when: "Find small-cap companies with ROE > 20% and low debt" -> query="Market Capitalization < 5000 AND Return on equity > 20 AND Debt to equity < 0.3"

  • Don't use when: You want data for one specific known company (use screener_get_company_overview instead)

Error Handling:

  • Returns "Error: Screener rejected this query: ..." if the query syntax is invalid — check field names and operators.

  • If truncated=true and totalFound is much larger than what's returned, note that a logged-in session would unlock more rows.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of result rows to return (default 25, max 100). Guest access is capped by Screener regardless of this value.
queryYesScreener.in query-builder syntax, e.g. "Market Capitalization > 500 AND Return on equity > 22". Combine conditions with AND/OR. Common fields: Market Capitalization, Current Price, Price to Earning, Return on equity, Return on capital employed, Debt to equity, Sales growth, Profit growth, Dividend yield, Book value.

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it explains the guest session cap on results, details error response formats, and describes the return structure. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections: purpose, arguments, returns, examples, and error handling. It is front-loaded with the core action. Every sentence adds value without redundancy. The length is appropriate for the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 2 parameters with 100% schema coverage, moderate complexity (custom query syntax), and no output schema, the description is complete. It explains the query language, provides examples, covers guest limitations, details return format, and addresses error scenarios. It also references sibling tools for comparison.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds significant value by providing examples of query syntax, listing common financial fields, explaining the limit parameter's behavior under guest access, and giving practical usage patterns. This goes beyond the schema's minimal descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it runs a custom stock screen using Screener.in's query-builder syntax against financial data and returns matching companies. It distinguishes from siblings by explicitly noting it is for screening multiple companies at once, and provides a 'Don't use when' example that names the sibling tool for individual companies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use context (core screener feature) and when-not-to-use (use screener_get_company_overview for single companies). It includes example use cases and queries, error handling guidance, and notes about guest session limits. It clearly states when to prefer alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

screener_search_companiesSearch Companies on Screener.inA
Read-onlyIdempotent

Search Screener.in for listed Indian companies by name or ticker symbol.

Use this first when you're not sure of a company's exact ticker or how Screener.in identifies it — the result's "id" or "url" can be passed as the identifier to the other screener_* tools.

Args:

  • query (string): Company name or ticker, e.g. "TCS", "Infosys", "HDFC Bank"

Returns: JSON with a "results" array, each item having: { "id": string, "name": string, "url": string (relative screener.in path) }

Examples:

  • Use when: "Find the ticker for Tata Consultancy Services" -> query="Tata Consultancy"

  • Don't use when: You already have the exact ticker (just call screener_get_company_overview directly)

Error Handling:

  • Returns an empty "results" array if nothing matches

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesCompany name or ticker symbol to search for, e.g. 'TCS' or 'Tata Consultancy'

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds detail about return format (JSON with results array, empty array on no match) and the relative URL structure, which provides helpful behavioral context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise and well-structured with separate sections for Args, Returns, Examples, and Error Handling. Every sentence adds value; no redundant or vague language.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple search tool with one parameter and high schema coverage, the description is fully complete. It covers purpose, usage, return format, error behavior, and integration with sibling tools. No gaps remain for an agent to guess.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with the single 'query' parameter already described. The description adds value by providing concrete examples ('TCS', 'Infosys', 'HDFC Bank') and specifying the max length (100 chars) from schema, helping agents choose correct input format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches Screener.in for listed Indian companies by name or ticker symbol. It distinguishes from sibling tools by indicating this is the first step when unsure of the exact identifier, and specifies the output contains 'id', 'name', and 'url' for use with other screener tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is provided: use when unsure of exact ticker, and don't use when you already have the ticker (instead call screener_get_company_overview directly). Examples reinforce correct usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv1.0.0
    • First observedscreener_get_company_overview
    • First observedscreener_get_financial_statement
    • First observedscreener_get_peer_comparison
    • First observedscreener_run_custom_screen
    • First observedscreener_search_companies
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.7/5.0

Scored across 5 tools

Disambiguation5/5

Each tool targets a distinct aspect: company overview, financial statements, peer comparison, custom screening, and company search. No functional overlap; descriptions clearly differentiate them.

Naming Consistency5/5

All tool names follow the 'screener_verb_noun' pattern (e.g., screener_get_company_overview, screener_search_companies). Naming is uniform and predictable.

Tool Count5/5

With 5 tools, the server covers the essential functionalities for fundamental stock analysis without excess or deficiency. Each tool earns its place.

Completeness5/5

The tool set covers all major Screener.in features: company snapshot, multi-period financials, peer comparison, custom screening, and search. No obvious gaps for the intended domain.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Daito

    achaljhawar
    F
    license
    Not graded
    quality
    D
    maintenance
    MCP server for screening Indian stocks and mutual funds by wrapping screener.in and Morningstar India, enabling fundamental queries from Claude or Cursor.
    -

  • screener-mcp

    aryamanw
    A
    license
    Not graded
    quality
    B
    maintenance
    MCP server that provides access to screener.in financial data for Indian stocks, enabling queries for company info, financials, ratios, quarterly results, shareholding, and stock screening.
    MIT

  • screener-mcp-pro

    vidyasagardivi9
    A
    license
    A
    quality
    C
    maintenance
    MCP server providing fundamental and technical data on Indian-listed companies from Screener.in and Yahoo Finance, including financial statements, ratios, and technical indicators.
    12
    MIT