FinStack MCP

FinStack MCP

95 free tools for Indian + global markets. Works inside Claude, Cursor, and any MCP client.

Open-source market intelligence for Indian equities, global markets, and MCP-native AI workflows. Ask one question like Should I buy Reliance? and get debate, sentiment, smart-money, risk, peer context, and ranking in one stack.

[PyPI] [License: MIT] [Python 3.10+]

pip install finstack-mcp

Or run without installing:

uvx finstack-mcp

Ask Claude things like:

"Give me a full stock brief on Reliance"-> 6 AI agents debate: FII Desk + Algo Trader + Value Investor + Retail Pulse + Macro Analyst + Options Flow-> Consensus: BUY/HOLD/SELL with reasoning
"Is someone accumulating HDFC Bank quietly?"-> Checks OI buildup, block deals, promoter buying, volume spike simultaneously
"What's the social buzz on TCS before results?"-> StockTwits + Reddit + Economic Times -> 67% bullish | Signal: HOLD
"Will Nifty go up tomorrow?"-> RSI + FII flow + PCR + VIX + G-Sec + GIFT Nifty -> 63% probability up
"Should I take a NIFTY CE or PE today?"-> Intraday F&O setup -> BUY_CE / BUY_PE / NO_TRADE with ATM strike zone, confidence, and approval-ready summary
"Give me the 8:15 AM F&O brief"-> GIFT Nifty + VIX + NIFTY setup + BANKNIFTY setup -> ready-to-forward morning note
"Scan my portfolio for risk"-> Sector concentration, pledged promoters, FII exposure, XIRR, diversification score
"Is this Telegram stock tip channel a scam?"-> Accuracy %, avg return %, pump-and-dump probability scored

Demo preview

Stock brief in action

[Stock Brief Demo]

Agent battle visualization

[Agent Battle Demo]

Example outputs

[Stock Brief Output]

[FII Flow Output]

Launch resources

• Proof and accuracy notes
• GitHub launch copy and positioning
• Release checklist

Why this is different

• Built for Indian markets first, not as a US-market wrapper with a few NSE tickers added later
• MCP-native, so it works inside Claude, Cursor, and other agent workflows instead of being just another dashboard
• Combines data, scoring, debate, and research workflows instead of forcing users to stitch 5 paid tools together
• Includes tools competitors usually do not offer at all: stock debate, watchlist ranking, stock timeline, Telegram tracker, GST-to-stock context, and budget analyzer

What this replaces

Install + connect (2 minutes)

pip install finstack-mcp

Claude Desktop

Add to claude_desktop_config.json:

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

{  "mcpServers": {    "finstack": {      "command": "python",      "args": ["-m", "finstack.server"]    }  }}

Restart Claude Desktop. Done.

Cursor / Windsurf / Cline

{  "mcpServers": {    "finstack": {      "command": "python",      "args": ["-m", "finstack.server"]    }  }}

Add to your IDE's MCP config file and reload.

uvx (no install needed)

{  "mcpServers": {    "finstack": {      "command": "uvx",      "args": ["finstack-mcp"]    }  }}

Works with: Claude Desktop · Cursor · Windsurf · Cline · Continue.dev · Zed · Jan.ai · LibreChat · any MCP client

Remote MCP publishing roadmap

If 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.

What to build for remote HTTP

• Expose FinStack through a public MCP endpoint over HTTPS, preferably Streamable HTTP or SSE.
• Add OAuth before opening it to outside users.
• Keep tool descriptions narrow, clear, and safe.
• Add rate limiting, monitoring, and a visible support contact.
• Publish a privacy policy and terms before any official submission.

ChatGPT / OpenAI path

• Host a remote MCP server that is reachable over HTTPS.
• Test it first as a custom connector or custom app in ChatGPT.
• Add connector-friendly read tools such as search and fetch if you want broader compatibility with OpenAI connector flows.
• Keep FinStack-specific tools like get_stock_brief, get_stock_debate, get_social_sentiment, and analyze_portfolio as domain tools on top.

Claude / Anthropic path

• First make sure the server works as a custom connector.
• Then prepare for directory review instead of assuming instant listing.
• Anthropic reviews third-party MCP servers for safety, security, privacy, and compatibility before directory inclusion.
• Directory listing is not guaranteed even if the server is technically valid.

Practical submission checklist

• Public HTTPS MCP endpoint
• OAuth login flow
• Stable server uptime
• Safe tool scope and descriptions
• Privacy policy
• Terms of service
• Support email or issue tracker
• Clear docs and example prompts
• No tool behavior that encourages bypassing model safety policies

Recommended product split

• Local stdio MCP: best for developers and power users
• Hosted remote MCP: best for connectors and wider distribution
• Separate hosted FinStack web UI: best place for premium visuals like Agent Battle

This keeps MCP as the execution layer and your own frontend as the premium experience.

95 tools across 10 categories

Indian Markets (live data)

• NSE/BSE real-time quotes, OHLCV history, market status
• Nifty 50, Bank Nifty, Sensex indices
• FII/DII institutional flows (daily + historical)
• Bulk & block deals, circuit breaker scanner, 52W high/low scanner
• Mutual fund NAV, corporate actions, earnings calendar, IPO calendar

AI Intelligence (unique to finstack-mcp)

• get_stock_brief — 6 AI agents debate any stock → BUY/HOLD/SELL consensus
• get_stock_debate — 3-round sequential agent debate with rebuttals and emergent consensus
• get_social_sentiment — StockTwits + Reddit + ET RSS → sentiment signal
• detect_unusual_activity — OI buildup + block deals + promoter change + volume spike
• get_nifty_outlook — 6-signal probability model for next session direction
• get_fno_trade_setup — NIFTY / BANKNIFTY options call: BUY_CE, BUY_PE, or NO_TRADE with ATM strike guidance
• predict_earnings — beat/miss probability before quarterly results
• get_fii_retail_divergence — highest-conviction Indian market signal
• get_morning_fno_brief — daily NIFTY/BANKNIFTY F&O brief with approval-ready setup summary

Research & Ranking

• scan_watchlist — batch-rank a watchlist so automation can surface top buys and top risks
• get_stock_signal_score — automation-friendly score with factor impacts, supports, and risks
• get_stock_timeline — one feed for news, results, insider, bulk deals, sentiment, pledge, and smart money
• get_sector_peer_context — sector strength plus peer rank / valuation context
• evaluate_signal_quality — honest proof layer for the price-action core before making accuracy claims

Portfolio & Risk

• analyze_portfolio — P&L, XIRR, sector concentration, risk flags, diversification score
• get_mf_overlap — fund overlap % from AMFI public disclosures
• get_pledge_alert — promoter pledge early warning with QoQ velocity
• scan_pledge_risks — batch pledge scan across your watchlist
• predict_circuit — lower circuit risk prediction
• detect_pump — pump-and-dump pattern detector for small/micro caps

Broker Integrations (zero-delay live data)

• Angel One SmartAPI — live quotes, Level 2 depth, intraday candles
• Fyers API v3 — live quotes + candles
• ICICI Breeze — live quotes + candles
• Dhan SmartAPI — live quotes + candles
• Upstox API v2 — live quotes + candles

Options & Greeks

• Full NSE options chain with PCR, Open Interest, Max Pain
• Black-Scholes Greeks: Delta, Gamma, Theta, Vega, Rho
• OI analytics, IV summary, top OI strikes

Market Intelligence

• India VIX + signal, GIFT Nifty pre-market
• NSE insider trading (SAST filings), promoter shareholding + pledge %
• RBI policy rates, India macro (CPI, GDP, CAD)
• AMFI mutual fund flows, India G-Sec yield curve
• get_sebi_alerts — SEBI enforcement order tracker (early crash warning)
• get_morning_brief — 8:15 AM pre-market brief

Never-built-before (India-specific)

• correlate_gst_to_stocks — GST monthly data as 1-3mo sector leading indicator
• get_agm_brief — AGM/EGM unusual resolution detector (debt raise, salary hike, pledge approval)
• get_insider_signal — SEBI SAST insider buy/sell pattern vs forward returns
• get_telegram_tracker — Dalal Street tip channel accuracy + pump-and-dump scoring
• analyze_budget_live — paste FM speech → instant sector/stock signals (Feb 1st)
• get_budget_impact — historical Union Budget winners + losers by year

Fundamentals

• Income statement, balance sheet, cash flow (Indian + US)
• Key ratios: P/E, ROE, margins, debt/equity, growth
• Company profile, dividend history (10-year), stock comparison

Global + Crypto + Tax

• US, EU, global equities — quotes + history
• Crypto: BTC, ETH, SOL, 100+ coins (CoinGecko)
• Forex: USD/INR, EUR/INR, 50+ pairs
• SEC filings (10-K, 10-Q, 8-K)
• LTCG/STCG tax calculator (post-July 2024 Budget rules — nobody else has this)

Accuracy and evaluation

FinStack should be presented as a decision-support engine, not as a guaranteed prediction machine.

• get_stock_signal_score is a ranking layer for triage, screening, and automation
• evaluate_signal_quality is an honest proof layer for the price-action core
• 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"
• safest language for users: signal engine, research assistant, multi-factor ranking, and decision-support

Comparison vs Indian market tools

Real-time data (optional)

Without setup: 15-minute delayed data (yfinance — free, no API key). With Angel One: zero delay, Level 2 order book, intraday candles.

pip install finstack-mcp[broker]

ANGEL_API_KEY=your_keyANGEL_CLIENT_ID=your_client_idANGEL_PASSWORD=your_pinANGEL_TOTP_SECRET=your_totp_secret

Free account at smartapi.angelbroking.com. Your key stays local in .env — never leaves your machine.

Other brokers: Fyers, ICICI Breeze, Dhan, Upstox also supported.

Data sources

Troubleshooting

Claude says "finstack not found" after install

• Restart Claude Desktop fully (quit from system tray, not just close)
• Config path on Windows: %APPDATA%\Claude\claude_desktop_config.json
• Verify Python is in PATH: python --version

pip install fails

python -m pip install --upgrade pippip install finstack-mcp

Angel One TOTP fails

• TOTP secret ≠ password. Find it in Angel One app → Profile → Enable TOTP → secret key
• Install: pip install finstack-mcp[broker]

Development

git clone https://github.com/finstacklabs/finstack-mcp.gitcd finstack-mcppip install -e .[dev]pytest -q

PRs welcome. Adding a new broker: create src/finstack/data/broker_X.py and register in tools/.

Links

• PyPI: https://pypi.org/project/finstack-mcp/
• Landing page: https://finstacklabs.github.io/
• YouTube: https://youtu.be/PWK89gBbHEM
• X: https://x.com/finstacklabs1

MIT License · finstacklabs.github.io