Stocker

Author: Ankit Surana (ankitsurana002@gmail.com)

A Python MCP server for NSE (Indian stock market) research. Screen stocks by P/E, momentum, and market cap, get quotes and history, compare a stock against its sector peers, check watchlist diversification, save alerts, and pull upcoming corporate events. All data comes from Yahoo Finance (free, no API key). Everything is a switch in config.json: add another data source later without touching any other file.

Setup

cd stocker-mcp
python3 -m venv venv
./venv/bin/pip install -r requirements.txt

That installs mcp, requests, and curl_cffi. The Yahoo provider needs curl_cffi to look like a browser. Without it the server starts but every data call fails.

Open Claude Desktop, go to Settings, then Developer, then click Edit Config. Add this entry (use your actual path):

{
  "mcpServers": {
    "stocker": {
      "command": "/absolute/path/to/stocker-mcp/venv/bin/python",
      "args": ["/absolute/path/to/stocker-mcp/server.py"]
    }
  }
}

Fully quit and reopen Claude Desktop. Check Settings, then Developer, or the connectors list, to confirm "stocker" is running.

A full research session

This is one end-to-end flow: you type plain English on the left, Claude picks the tool and arguments, and the server returns JSON. The responses below are real (numbers rounded, some fields trimmed for readability) so you can see the exact shape of what comes back.

1. See what you can screen

You: What NSE indices can you screen?

Calls list_indices():

{ "indices": ["NIFTY 50", "NIFTY NEXT 50", "NIFTY 100", "NIFTY IT",
              "NIFTY BANK", "NIFTY AUTO", "NIFTY PHARMA", "NIFTY FMCG",
              "NIFTY METAL", "NIFTY ENERGY", "NIFTY REALTY", "NIFTY MEDIA",
              "NIFTY FIN SERVICE", "..."] }

2. Screen an index

You: Screen NIFTY IT for stocks with a P/E under 25.

Calls screen_stocks(index="NIFTY IT", pe_max=25, max_results=3):

{
  "index": "NIFTY IT",
  "dataSource": "yahoo_finance",
  "filters": { "pe_max": 25, "pe_min": null, "min_30d_change_pct": null, "market_cap": "any" },
  "matchCount": 3,
  "results": [
    { "symbol": "HCLTECH", "lastPrice": 1156.0, "pChange": 0.91, "change30dPct": 0.85,  "marketCapBucket": "large", "peRatio": 19.22, "sector": "Technology" },
    { "symbol": "MPHASIS", "lastPrice": 2267.1, "pChange": 1.12, "change30dPct": -3.14, "marketCapBucket": "mid",   "peRatio": 24.60, "sector": "Technology" },
    { "symbol": "WIPRO",   "lastPrice": 173.6,  "pChange": 0.51, "change30dPct": -4.44, "marketCapBucket": "large", "peRatio": 13.84, "sector": "Technology" }
  ]
}

market_cap accepts large / mid / small / any; add pe_min for a range or min_30d_change_pct for a momentum floor.

3. Today's movers

You: Who are today's top gainers in NIFTY IT?

Calls get_top_movers(index="NIFTY IT", direction="gainers", count=3) (pass direction="losers" for the other end):

{
  "index": "NIFTY IT", "direction": "gainers", "dataSource": "yahoo_finance",
  "top": [
    { "symbol": "LTTS",       "lastPrice": 3210.6, "pChange": 2.21, "perChange30d": -6.06, "marketCapProxy": 34054 },
    { "symbol": "COFORGE",    "lastPrice": 1472.7, "pChange": 1.85, "perChange30d": 4.33,  "marketCapProxy": 65195 },
    { "symbol": "PERSISTENT", "lastPrice": 4843.9, "pChange": 1.56, "perChange30d": -3.48, "marketCapProxy": 75677 }
  ]
}

(marketCapProxy is in ₹ crore; perChange30d is the 30-day % move.)

4. Quote a stock

You: Get me a quote on TCS.

Calls get_stock_quote(symbol="TCS"):

{
  "symbol": "TCS", "lastPrice": 2048.5, "change": -9.0, "pChange": -0.44,
  "peRatio": 15.34, "sector": "Technology", "eps": 133.53,
  "dataSource": "yahoo_finance"
}

5. Compare against sector peers

You: How does TCS stack up against its IT peers?

Calls get_peer_comparison(symbol="TCS", max_peers=3). It reads TCS's real sector, pulls the matching sector index, and ranks peers by how close their P/E is to TCS's:

{
  "symbol": "TCS", "sector": "Technology", "peRatio": 15.34,
  "peers": [
    { "symbol": "INFY",    "lastPrice": 1056.8, "peRatio": 14.04, "pChange": -1.17 },
    { "symbol": "WIPRO",   "lastPrice": 173.6,  "peRatio": 13.84, "pChange": 0.51 },
    { "symbol": "HCLTECH", "lastPrice": 1155.5, "peRatio": 19.21, "pChange": 0.86 }
  ]
}

6. Build and inspect a watchlist

You: Start a watchlist called my_picks with TCS and HDFCBANK.

Two watchlist_add(list_name="my_picks", symbol=...) calls give { "my_picks": ["TCS", "HDFCBANK"] }

You: Is my_picks concentrated in any one sector?

Calls check_watchlist_diversification(list_name="my_picks"):

{
  "list": "my_picks", "totalSymbols": 2,
  "sectorBreakdown": [
    { "sector": "Technology",         "count": 1, "pctOfList": 50.0 },
    { "sector": "Financial Services", "count": 1, "pctOfList": 50.0 }
  ],
  "concentrationWarnings": ["No single sector dominates, reasonably diversified"]
}

(A sector at ≥40% of the list triggers a concentration warning.) watchlist_view(list_name) shows one list (or all lists if omitted), and watchlist_remove(list_name, symbol) drops a symbol.

7. Set and check alerts

You: Alert me if TCS P/E drops below 14.

Calls add_watchlist_alert(symbol="TCS", condition="pe_below", value=14). Valid conditions: pe_below, pe_above, price_below, price_above, day_change_above_pct.

You: Did any of my alerts trigger?

Calls check_watchlist_alerts(). It checks every saved alert against live prices and returns which ones fired:

{ "checked": 1, "triggered": [], "errors": [] }

list_watchlist_alerts() shows everything you've saved. Pair check_watchlist_alerts with Claude's Scheduled Tasks to get a recurring check without running your own server.

8. Upcoming events

You: Anything coming up for TCS?

Calls get_upcoming_events(symbol="TCS"). Each event is tagged upcoming or past (Yahoo reports the most recent ex-dividend, which is usually already behind you), and earnings are marked confirmed vs estimated from Yahoo's own flag, with the consensus EPS/revenue for the quarter:

{
  "symbol": "TCS", "dataSource": "yahoo_finance",
  "announcements": [
    { "subject": "Earnings date (confirmed)", "date": "2026-07-09", "status": "upcoming",
      "consensus": { "epsEstimate": "37.33", "revenueEstimate": "720.42B" }, "attachment": null },
    { "subject": "Ex-dividend date", "date": "2026-05-25", "status": "past", "attachment": null }
  ]
}

9. Run a canned strategy

You: What strategies do you have? Run the momentum one.

list_strategies() returns value_picks, momentum_picks, large_cap_quality, midcap_momentum. Then run_strategy(strategy_name="momentum_picks") (strong 30-day gainers across the liquid universe):

{
  "strategy": "momentum_picks", "index": "NIFTY 500", "matchCount": 10,
  "results": [
    { "symbol": "LODHA",    "lastPrice": 1139.85, "change30dPct": 28.37, "marketCapBucket": "large" },
    { "symbol": "PRESTIGE", "lastPrice": 1666.2,  "change30dPct": 23.06, "marketCapBucket": "large" },
    { "symbol": "NAUKRI",   "lastPrice": 1201.75, "change30dPct": 22.30, "marketCapBucket": "large" }
  ]
}

10. Price history

You: Show me TCS daily prices this month.

Calls get_stock_history(symbol="TCS", start="2026-07-06", end="2026-07-09"). Daily OHLCV between two YYYY-MM-DD dates:

{
  "symbol": "TCS", "dataSource": "yahoo_finance",
  "history": [
    { "date": "2026-07-06", "open": 2090.0, "high": 2093.0, "low": 2050.6, "close": 2057.6, "volume": 2567386 },
    { "date": "2026-07-07", "open": 2050.0, "high": 2122.7, "low": 2049.0, "close": 2096.1, "volume": 4769048 },
    { "date": "2026-07-08", "open": 2094.0, "high": 2109.7, "low": 2048.8, "close": 2057.5, "volume": 3666985 },
    { "date": "2026-07-09", "open": 2057.5, "high": 2065.0, "low": 2016.0, "close": 2048.4, "volume": 2574241 }
  ]
}

Anytime: what's live

You: What data sources are active?

list_data_sources() reports every provider, whether it's enabled, and the priority per capability. Useful for checking what's live without opening config.json.

More example queries

You don't have to phrase things any particular way. Claude maps natural language to the right tool and parameters. Variations that all work:

Screening variations

• "Find me cheap pharma stocks" (screens NIFTY PHARMA with a low P/E cap)
• "Mid-cap stocks in NIFTY 500 that gained at least 10% this month"
• "Large-cap banks with P/E between 10 and 20" (uses both pe_min and pe_max)
• "Show me 5 small-cap momentum stocks" (caps max_results at 5)
• "Anything in NIFTY METAL under a P/E of 12?"

Quotes and comparisons

• "TCS price?" (short forms work fine)
• "Is Infosys expensive right now?" (quote, then its P/E vs its sector peers)
• "Compare HDFCBANK to other banks"
• "Which IT stock is closest to TCS in valuation?" (peer comparison, peers are ranked by P/E proximity)

Movers and history

• "Biggest losers today" (defaults to NIFTY 500)
• "Top 3 gainers in NIFTY AUTO"
• "How has Reliance moved since June 1st?"
• "TCS price on each day last week"

Watchlists

• "Start a watchlist called it_bets with TCS, INFY, and WIPRO" (three watchlist_add calls)
• "What's in it_bets?"
• "Drop WIPRO from it_bets"
• "Is my it_bets list too concentrated in one sector?"

Alerts

• "Tell me if INFY goes above 2000" (price_above)
• "Watch for TCS P/E under 22" (pe_below)
• "Flag anything in my alerts that moved more than 5% today" (day_change_above_pct)
• "Did any of my alerts trigger?" (evaluates all saved alerts)

Multi-tool questions

One question can chain several tools. Claude decides the sequence:

• "Screen NIFTY IT for P/E under 25, then add the top 3 to a watchlist called screen_results" (screen_stocks, then watchlist_add three times)
• "Is anything in my_picks reporting results soon?" (watchlist_view, then get_upcoming_events per symbol)
• "Compare everything in my_picks against their sector peers" (watchlist_view, then get_peer_comparison per symbol)
• "Run the value_picks strategy and alert me if the top result's P/E drops another 10%" (run_strategy, then add_watchlist_alert)

Analysis on top of the data

The tools return raw data. The reasoning happens in the conversation, so you can ask follow-ups with no extra tool support needed:

• "Which of these screener results looks most undervalued and why?"
• "Summarize the risk profile of my watchlist in two sentences"
• "Based on the 30 day history, is this stock trending up or consolidating?"

Notes

All data comes from yahoo_finance, a free source with no API key. It uses curl_cffi to reach Yahoo Finance, which sidesteps the bot blocking you hit when scraping NSE directly. It serves quotes (price, P/E, sector) and history. For the screener, movers, and peer-comparison tools it pulls index members live from the official niftyindices.com CSVs (cached per run), so the lists stay current across rebalances with nothing hardcoded.

The old providers (nse_scrape, alpha_vantage, kite_connect, upstox) were removed. NSE's site sits behind Akamai and blocks scripts, Alpha Vantage has no P/E or sector for Indian stocks, and the two broker APIs need a paid/OAuth setup that was never built. To add a new source, implement the interface in providers/base.py, register it in providers/manager.py, and list it in config.json.

Tests

A regression suite lives in tests/ (unit tests are hermetic and instant; integration tests hit the live APIs). Run it after any change:

./venv/bin/pip install -r requirements-dev.txt   # once
./venv/bin/python -m pytest                       # all
./venv/bin/python -m pytest -m "not integration"  # fast, offline

See tests/README.md for details.