Finstack MCP Server

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.

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

Agent battle visualization

Example outputs

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_key
ANGEL_CLIENT_ID=your_client_id
ANGEL_PASSWORD=your_pin
ANGEL_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 pip
pip 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.git
cd finstack-mcp
pip 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