Metadata-Version: 2.4
Name: dalal-mcp
Version: 0.1.0
Summary: Zero-config MCP server for Indian stock markets, with screening and market-breadth tools
Author: harsh0351
License: MIT
License-File: LICENSE
Keywords: bse,finance,india,mcp,model-context-protocol,nse,stocks
Requires-Python: >=3.11
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: yfinance>=0.2.40
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# dalal-mcp

**A zero-config, free MCP server for Indian stock markets — with screening and market-breadth tools no other Indian-markets MCP server offers.**

`dalal-mcp` lets any LLM client (Claude Desktop, Claude Code, OpenAI Codex, Cursor) query NSE/BSE equities in plain language. Unlike other Indian-markets MCP servers, it doesn't stop at quote lookup: it can **run a stock screen** and **read market internals** (StockBee-style breadth) — and it needs **no API key**.

```
"Which NIFTY stocks are up more than 4% today on above-average volume?"
"What's market breadth right now — how many stocks are above their 50-day average?"
"Give me Infosys fundamentals and its last month of prices."
```

## Why this one

- 🆓 **Zero-config & free.** Uses Yahoo Finance data (`.NS`/`.BO` tickers). No signup, no paid API key — unlike servers that require a paid data plan.
- 🔎 **Screening built in** (`screen_stocks`) — filter a universe by price, % change, volume, and moving-average crosses. No other Indian-markets MCP server does this.
- 📊 **Market breadth** (`market_breadth`) — advancers/decliners, new 52-week highs/lows, % of stocks above their 50/200-day moving averages.
- 🧱 **Reliable by design** — thin data layer, fully unit-tested tools, graceful per-symbol error handling.

## Install

```bash
uvx dalal-mcp
```

(Requires [`uv`](https://docs.astral.sh/uv/). No other setup.)

## Configure your client

**Claude Desktop / Claude Code** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "dalal": { "command": "uvx", "args": ["dalal-mcp"] }
  }
}
```

**OpenAI Codex / Cursor** — point your MCP config at the same command (`uvx dalal-mcp`, stdio transport).

## Tools

| Tool | What it does |
|------|--------------|
| `search_symbol` | Resolve a name/partial ticker to Indian-market symbols |
| `get_quote` | Latest price, day range, volume |
| `get_historical` | OHLCV candles over a period |
| `get_fundamentals` | P/E, market cap, EPS, sector, 52-wk range |
| `screen_stocks` | Filter a universe by numeric criteria |
| `market_breadth` | Advancers/decliners, new highs/lows, % above DMA |
| `get_index` | Index level + constituents (NIFTY 50, SENSEX) |

## Development

```bash
uv venv && uv pip install -e ".[dev]"
uv run pytest
```

Tests use mocked data — no network access required in CI.

## License

MIT
