{
  "markdown": "# FinStack MCP\n\n**95 free tools for Indian + global markets. Works inside Claude, Cursor, and any MCP client.**\n\nOpen-source market intelligence for Indian equities, global markets, and MCP-native AI workflows.\nAsk one question like `Should I buy Reliance?` and get debate, sentiment, smart-money, risk, peer context, and ranking in one stack.\n\n[![PyPI](https://badge.fury.io/py/finstack-mcp.svg)](https://pypi.org/project/finstack-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n\n```bash\npip install finstack-mcp\n```\n\nOr run without installing:\n\n```bash\nuvx finstack-mcp\n```\n\nAsk Claude things like:\n\n```text\n\"Give me a full stock brief on Reliance\"\n-> 6 AI agents debate: FII Desk + Algo Trader + Value Investor + Retail Pulse + Macro Analyst + Options Flow\n-> Consensus: BUY/HOLD/SELL with reasoning\n\n\"Is someone accumulating HDFC Bank quietly?\"\n-> Checks OI buildup, block deals, promoter buying, volume spike simultaneously\n\n\"What's the social buzz on TCS before results?\"\n-> StockTwits + Reddit + Economic Times -> 67% bullish | Signal: HOLD\n\n\"Will Nifty go up tomorrow?\"\n-> RSI + FII flow + PCR + VIX + G-Sec + GIFT Nifty -> 63% probability up\n\n\"Should I take a NIFTY CE or PE today?\"\n-> Intraday F&O setup -> BUY_CE / BUY_PE / NO_TRADE with ATM strike zone, confidence, and approval-ready summary\n\n\"Give me the 8:15 AM F&O brief\"\n-> GIFT Nifty + VIX + NIFTY setup + BANKNIFTY setup -> ready-to-forward morning note\n\n\"Scan my portfolio for risk\"\n-> Sector concentration, pledged promoters, FII exposure, XIRR, diversification score\n\n\"Is this Telegram stock tip channel a scam?\"\n-> Accuracy %, avg return %, pump-and-dump probability scored\n```\n\n## Demo preview\n\n### Stock brief in action\n\n![Stock Brief Demo](docs/assets/stock-brief-demo.gif)\n\n### Agent battle visualization\n\n![Agent Battle Demo](docs/assets/agent-battle-demo.gif)\n\n### Example outputs\n\n![Stock Brief Output](docs/assets/demo-brief.png)\n\n![FII Flow Output](docs/assets/demo-fii.png)\n\n## Launch resources\n\n- [Proof and accuracy notes](docs/PROOF_AND_ACCURACY.md)\n- [GitHub launch copy and positioning](docs/GITHUB_LAUNCH_KIT.md)\n- [Release checklist](docs/RELEASE_CHECKLIST.md)\n\n## Why this is different\n\n- Built for Indian markets first, not as a US-market wrapper with a few NSE tickers added later\n- MCP-native, so it works inside Claude, Cursor, and other agent workflows instead of being just another dashboard\n- Combines data, scoring, debate, and research workflows instead of forcing users to stitch 5 paid tools together\n- Includes tools competitors usually do not offer at all: stock debate, watchlist ranking, stock timeline, Telegram tracker, GST-to-stock context, and budget analyzer\n\n---\n\n## What this replaces\n\n| Tool | What you pay | finstack-mcp |\n|---|---|---|\n| Bloomberg Terminal | $31,980 / yr | **FREE** |\n| Bloomberg ESG + Credit | $24,000 / yr | **FREE** |\n| Sensibull (Options Greeks) | ₹15,600 / yr | **FREE** |\n| Morningstar (MF flows) | $17,500 / yr | **FREE** |\n| Zerodha real-time data | ₹6,000 / yr | **FREE** via Angel One |\n| Screener.in Pro | ₹4,999 / yr | **FREE** |\n| Trendlyne Pro | ₹4,950 / yr | **FREE** |\n\n---\n\n## Install + connect (2 minutes)\n\n```bash\npip install finstack-mcp\n```\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"finstack\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"finstack.server\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop. Done.\n\n### Cursor / Windsurf / Cline\n\n```json\n{\n  \"mcpServers\": {\n    \"finstack\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"finstack.server\"]\n    }\n  }\n}\n```\n\nAdd to your IDE's MCP config file and reload.\n\n### uvx (no install needed)\n\n```json\n{\n  \"mcpServers\": {\n    \"finstack\": {\n      \"command\": \"uvx\",\n      \"args\": [\"finstack-mcp\"]\n    }\n  }\n}\n```\n\nWorks with: **Claude Desktop · Cursor · Windsurf · Cline · Continue.dev · Zed · Jan.ai · LibreChat · any MCP client**\n\n---\n\n## Remote MCP publishing roadmap\n\nIf you want `finstack-mcp` to move beyond local desktop config and become available through connector ecosystems, keep the local `python -m finstack.server` setup for developers and add a hosted remote MCP version for public distribution.\n\n### What to build for remote HTTP\n\n- Expose FinStack through a public MCP endpoint over HTTPS, preferably Streamable HTTP or SSE.\n- Add OAuth before opening it to outside users.\n- Keep tool descriptions narrow, clear, and safe.\n- Add rate limiting, monitoring, and a visible support contact.\n- Publish a privacy policy and terms before any official submission.\n\n### ChatGPT / OpenAI path\n\n- Host a remote MCP server that is reachable over HTTPS.\n- Test it first as a custom connector or custom app in ChatGPT.\n- Add connector-friendly read tools such as `search` and `fetch` if you want broader compatibility with OpenAI connector flows.\n- Keep FinStack-specific tools like `get_stock_brief`, `get_stock_debate`, `get_social_sentiment`, and `analyze_portfolio` as domain tools on top.\n\n### Claude / Anthropic path\n\n- First make sure the server works as a custom connector.\n- Then prepare for directory review instead of assuming instant listing.\n- Anthropic reviews third-party MCP servers for safety, security, privacy, and compatibility before directory inclusion.\n- Directory listing is not guaranteed even if the server is technically valid.\n\n### Practical submission checklist\n\n- Public HTTPS MCP endpoint\n- OAuth login flow\n- Stable server uptime\n- Safe tool scope and descriptions\n- Privacy policy\n- Terms of service\n- Support email or issue tracker\n- Clear docs and example prompts\n- No tool behavior that encourages bypassing model safety policies\n\n### Recommended product split\n\n- Local stdio MCP: best for developers and power users\n- Hosted remote MCP: best for connectors and wider distribution\n- Separate hosted FinStack web UI: best place for premium visuals like Agent Battle\n\nThis keeps MCP as the execution layer and your own frontend as the premium experience.\n\n---\n\n## 95 tools across 10 categories\n\n### Indian Markets (live data)\n- NSE/BSE real-time quotes, OHLCV history, market status\n- Nifty 50, Bank Nifty, Sensex indices\n- FII/DII institutional flows (daily + historical)\n- Bulk & block deals, circuit breaker scanner, 52W high/low scanner\n- Mutual fund NAV, corporate actions, earnings calendar, IPO calendar\n\n### AI Intelligence (unique to finstack-mcp)\n- **`get_stock_brief`** — 6 AI agents debate any stock → BUY/HOLD/SELL consensus\n- **`get_stock_debate`** — 3-round sequential agent debate with rebuttals and emergent consensus\n- **`get_social_sentiment`** — StockTwits + Reddit + ET RSS → sentiment signal\n- **`detect_unusual_activity`** — OI buildup + block deals + promoter change + volume spike\n- **`get_nifty_outlook`** — 6-signal probability model for next session direction\n- **`get_fno_trade_setup`** — NIFTY / BANKNIFTY options call: BUY_CE, BUY_PE, or NO_TRADE with ATM strike guidance\n- **`predict_earnings`** — beat/miss probability before quarterly results\n- **`get_fii_retail_divergence`** — highest-conviction Indian market signal\n- **`get_morning_fno_brief`** — daily NIFTY/BANKNIFTY F&O brief with approval-ready setup summary\n\n### Research & Ranking\n- **`scan_watchlist`** — batch-rank a watchlist so automation can surface top buys and top risks\n- **`get_stock_signal_score`** — automation-friendly score with factor impacts, supports, and risks\n- **`get_stock_timeline`** — one feed for news, results, insider, bulk deals, sentiment, pledge, and smart money\n- **`get_sector_peer_context`** — sector strength plus peer rank / valuation context\n- **`evaluate_signal_quality`** — honest proof layer for the price-action core before making accuracy claims\n\n### Portfolio & Risk\n- **`analyze_portfolio`** — P&L, XIRR, sector concentration, risk flags, diversification score\n- **`get_mf_overlap`** — fund overlap % from AMFI public disclosures\n- **`get_pledge_alert`** — promoter pledge early warning with QoQ velocity\n- **`scan_pledge_risks`** — batch pledge scan across your watchlist\n- **`predict_circuit`** — lower circuit risk prediction\n- **`detect_pump`** — pump-and-dump pattern detector for small/micro caps\n\n### Broker Integrations (zero-delay live data)\n- Angel One SmartAPI — live quotes, Level 2 depth, intraday candles\n- Fyers API v3 — live quotes + candles\n- ICICI Breeze — live quotes + candles\n- Dhan SmartAPI — live quotes + candles\n- Upstox API v2 — live quotes + candles\n\n### Options & Greeks\n- Full NSE options chain with PCR, Open Interest, Max Pain\n- Black-Scholes Greeks: Delta, Gamma, Theta, Vega, Rho\n- OI analytics, IV summary, top OI strikes\n\n### Market Intelligence\n- India VIX + signal, GIFT Nifty pre-market\n- NSE insider trading (SAST filings), promoter shareholding + pledge %\n- RBI policy rates, India macro (CPI, GDP, CAD)\n- AMFI mutual fund flows, India G-Sec yield curve\n- **`get_sebi_alerts`** — SEBI enforcement order tracker (early crash warning)\n- **`get_morning_brief`** — 8:15 AM pre-market brief\n\n### Never-built-before (India-specific)\n- **`correlate_gst_to_stocks`** — GST monthly data as 1-3mo sector leading indicator\n- **`get_agm_brief`** — AGM/EGM unusual resolution detector (debt raise, salary hike, pledge approval)\n- **`get_insider_signal`** — SEBI SAST insider buy/sell pattern vs forward returns\n- **`get_telegram_tracker`** — Dalal Street tip channel accuracy + pump-and-dump scoring\n- **`analyze_budget_live`** — paste FM speech → instant sector/stock signals (Feb 1st)\n- **`get_budget_impact`** — historical Union Budget winners + losers by year\n\n### Fundamentals\n- Income statement, balance sheet, cash flow (Indian + US)\n- Key ratios: P/E, ROE, margins, debt/equity, growth\n- Company profile, dividend history (10-year), stock comparison\n\n### Global + Crypto + Tax\n- US, EU, global equities — quotes + history\n- Crypto: BTC, ETH, SOL, 100+ coins (CoinGecko)\n- Forex: USD/INR, EUR/INR, 50+ pairs\n- SEC filings (10-K, 10-Q, 8-K)\n- **LTCG/STCG tax calculator** (post-July 2024 Budget rules — nobody else has this)\n\n---\n\n## Accuracy and evaluation\n\nFinStack should be presented as a decision-support engine, not as a guaranteed prediction machine.\n\n- `get_stock_signal_score` is a ranking layer for triage, screening, and automation\n- `evaluate_signal_quality` is an honest proof layer for the price-action core\n- the full live system also uses sentiment, insider activity, pledge risk, macro, and peer context, so one backtest number should not be marketed as \"the accuracy of FinStack\"\n- safest language for users: `signal engine`, `research assistant`, `multi-factor ranking`, and `decision-support`\n\n---\n\n## Comparison vs Indian market tools\n\n| Feature | finstack-mcp | Screener.in | Tickertape | Sensibull | Trendlyne | TradingView |\n|---|---|---|---|---|---|---|\n| AI agents debate a stock | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| Social sentiment (Reddit + StockTwits) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| Nifty direction probability | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| Telegram tip channel tracker | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| Budget speech live analyzer | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| GST → sector stock predictor | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| Pump-and-dump detector | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| Promoter pledge early warning | ✅ | ❌ | ✅ paid | ❌ | ✅ paid | ❌ |\n| Options Greeks | ✅ free | ❌ | ❌ | ✅ ₹1,300/mo | ❌ | ✅ paid |\n| FII/DII flows | ✅ free | ❌ | ✅ | ✅ | ✅ paid | ❌ |\n| Fundamentals (P/E, ROE, etc.) | ✅ free | ✅ free | ✅ | ❌ | ✅ | ✅ paid |\n| Works inside Claude / Cursor | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| Price | **Free** | ₹4,999/yr | ₹2,800/yr | ₹15,600/yr | ₹4,950/yr | $168/yr |\n\n---\n\n## Real-time data (optional)\n\nWithout setup: 15-minute delayed data (yfinance — free, no API key).\nWith Angel One: zero delay, Level 2 order book, intraday candles.\n\n```bash\npip install finstack-mcp[broker]\n```\n\n```env\nANGEL_API_KEY=your_key\nANGEL_CLIENT_ID=your_client_id\nANGEL_PASSWORD=your_pin\nANGEL_TOTP_SECRET=your_totp_secret\n```\n\nFree account at [smartapi.angelbroking.com](https://smartapi.angelbroking.com/). Your key stays local in `.env` — never leaves your machine.\n\nOther brokers: Fyers, ICICI Breeze, Dhan, Upstox also supported.\n\n---\n\n## Data sources\n\n| Source | Covers | Key needed |\n|---|---|---|\n| yfinance | NSE/BSE/US equities, crypto, forex, history | None |\n| NSE direct API | FII/DII, options chain, insider trading, corporate actions | None |\n| BSE India API | Credit ratings, ESG/BRSR | None |\n| SEC EDGAR | US filings (10-K, 10-Q, 8-K) | None |\n| CoinGecko | Crypto market data | None |\n| World Bank | India macro: CPI, GDP, CAD | None |\n| AMFI / mfapi.in | Mutual fund NAV, AUM, SIP flows | None |\n| StockTwits | Trader sentiment (pre-tagged bullish/bearish) | None |\n| Reddit (praw) | r/IndiaInvestments + r/DalalStreetTalks | Optional free |\n| Finance Ministry | Monthly GST collection data | None |\n| SEBI public filings | Enforcement orders, insider SAST disclosures | None |\n| Angel One SmartAPI | Real-time NSE, Level 2 depth, intraday | Free account |\n\n---\n\n## Troubleshooting\n\n**Claude says \"finstack not found\" after install**\n- Restart Claude Desktop fully (quit from system tray, not just close)\n- Config path on Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- Verify Python is in PATH: `python --version`\n\n**pip install fails**\n```bash\npython -m pip install --upgrade pip\npip install finstack-mcp\n```\n\n**Angel One TOTP fails**\n- TOTP secret ≠ password. Find it in Angel One app → Profile → Enable TOTP → secret key\n- Install: `pip install finstack-mcp[broker]`\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/finstacklabs/finstack-mcp.git\ncd finstack-mcp\npip install -e .[dev]\npytest -q\n```\n\nPRs welcome. Adding a new broker: create `src/finstack/data/broker_X.py` and register in `tools/`.\n\n---\n\n## Links\n\n- PyPI: https://pypi.org/project/finstack-mcp/\n- Landing page: https://finstacklabs.github.io/\n- YouTube: https://youtu.be/PWK89gBbHEM\n- X: https://x.com/finstacklabs1\n\n---\n\nMIT License · [finstacklabs.github.io](https://finstacklabs.github.io/)\n",
  "bytes": 14256,
  "sha": "460d15e085d99bf8ab2e2d0c68a6f9e630c92eb712ab7c617f2d56c582f4dae0",
  "repo_slug": "finstacklabs/finstack-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_finstacklabs_finstack_mcp_daaa23fc/readme"
}