# screener-mcp

An MCP (Model Context Protocol) server that provides financial data for Indian listed companies from [screener.in](https://www.screener.in). Use it with Claude Desktop or any MCP-compatible client to query stock fundamentals, financial statements, and peer comparisons directly in your AI conversations.

## Features

- Search companies by name or ticker symbol
- Fetch financial data (P&L, balance sheet, cash flow, ratios, peers, shareholding)
- Supports both consolidated and standalone financials
- Request only the fields you need to keep responses concise
- Results cached for 5 minutes — repeated calls for the same company are instant
- No API key required — uses screener.in's public data

## Tools

| Tool | Description |
|------|-------------|
| `search_company` | Search for a company by name or ticker |
| `get_company_data` | Financial data for a company. Use the optional `fields` parameter to fetch only what you need |

### `get_company_data` fields

Pass a `fields` array to limit the response to only the sections you need:

| Field | Description |
|-------|-------------|
| `ratios` | Key financial ratios (Market Cap, P/E, P/B, ROE, ROCE, etc.) |
| `quarterly_results` | Quarterly revenue, profit, and EPS |
| `profit_loss` | Annual profit & loss statement |
| `balance_sheet` | Annual balance sheet |
| `cash_flow` | Annual cash flow statement |
| `shareholding` | Promoter / FII / DII shareholding pattern |
| `peers` | Peer comparison table |

Omit `fields` to fetch all sections at once.

## Prerequisites

- Node.js 18+
- npm

## Installation

```bash
git clone <repo-url>
cd screener-mcp
npm install
npm run build
```

## Usage with Claude Desktop

Add the following to your Claude Desktop config file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

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

Restart Claude Desktop after saving the config.

## Usage with Claude Code

Run this command after building (replace the path with where you cloned the repo):

```bash
claude mcp add screener -- node "/absolute/path/to/screener-mcp/dist/index.js"
```

Add `--scope global` to make it available in all projects:

```bash
claude mcp add --scope global screener -- node "/absolute/path/to/screener-mcp/dist/index.js"
```

## Development

```bash
# Run in development mode (no build step needed)
npm run dev

# Build for production
npm run build

# Run production build
npm start
```

## Tech Stack

- **TypeScript** with ES2022 modules
- **[@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)** — MCP server framework
- **[cheerio](https://cheerio.js.org/)** — HTML parsing / web scraping
- Native `fetch` for HTTP requests

## Example Prompts

Once configured, you can ask Claude things like:

- "What are the key financial ratios for Reliance Industries?"
- "Show me the quarterly results for TCS"
- "Compare HDFC Bank with its peers"
- "Get the balance sheet for Infosys for the last 5 years"
- "Search for companies with the name 'Tata'"

## Notes

- Data is scraped from screener.in's public pages — no login required for most data
- Results depend on screener.in's availability and HTML structure
- Financial data is sourced from BSE/NSE filings as aggregated by screener.in