🧠 stock_market_mcp

FoodForBrains · Feeding your brain the data it needs to decide.

stock_market_mcp is a Model Context Protocol (MCP) server for stock research and screening. It exposes a verified-data layer that gives AI clients grounded market information for NSE/BSE and US equities, with a simple BUY/HOLD/SELL scoring model layered on top.

The server is designed for clients such as ZCode, Claude Desktop, and other MCP-compatible hosts. It keeps the LLM reasoning layer thin and pushes the data retrieval, calculations, and audit trail into the server.

📖 Full docs: the wiki

What it does

• Covers Indian equities (NSE/BSE) and US tickers.

• Exposes 20 MCP tools plus 1 prompt.

• Uses Yahoo Finance as the default data source for quotes, history, fundamentals, and news.

• Adds NSE/BSE market mover data from public exchange endpoints with 10-minute cache handling.

• Supports a MongoDB-backed decision journal with a local JSON fallback.

• Produces auditable data_snapshot blocks so recommendation claims can be traced back to data.

Related MCP server: Rozkoduj MCP

Core facts

Tool set

Market and quote tools

• get_quote — current price, previous close, change %

• search_symbol — resolve company names to symbols with India-first ranking

• technical_analysis — SMA 20/50/200, RSI-14, MACD, 52-week range, daily volatility

• market_movers — NSE/BSE gainers/losers + index levels

• stock_news — recent headlines for one symbol

• earnings_calendar — earnings dates, EPS estimates, surprise history

Analysis tools

• analyze_stock — full technical + fundamental score (0–100), BUY/HOLD/SELL, reasons, data snapshot

• analyze_watchlist — rank a list of symbols by score

• compare_stocks — side-by-side fundamentals for multiple symbols

• stock_screener — filter by valuation, RSI, dividend yield, ROE, and score

• correlation_analysis — correlation, beta, r-squared against a benchmark

Fundamental and market context tools

• currency_impact — INR vs USD return comparison

• dividend_calendar — yield, ex-dividend, historical payouts

• options_data — options chain IV, put/call ratios, ATM details

• sector_mapping — sector, industry, peers, market cap, key metrics

• fii_dii_flows — institutional holders, mutual-fund holders, insider activity where available

Journal and workflow tools

• log_decision — record a BUY/HOLD/SELL call with rationale

• review_decisions — score open journal entries against current prices

• analyst_reports — generate fundamentals, technical, and sentiment reports for one symbol

Prompt

• bull_bear_debate — TradingAgents-style workflow: gather data → bull case → bear case → risk check → decision → journal it

Symbol formats

Setup

Prerequisites

• Python 3.10+

• pip

• An MCP client such as ZCode or Claude Desktop

• Optional: Alpha Vantage API key for alpha_vantage_overview

• Optional: MongoDB for decision-journal persistence

Install

git clone https://github.com/AnupamSinha/stock_market_mcp.git
cd stock_market_mcp
pip install -r requirements.txt

Optional environment config

Create a .env file in the project root (or export the same env vars):

ALPHA_VANTAGE_API_KEY=your_key_here
ALPHA_VANTAGE_BASE_URL=https://www.alphavantage.co/query
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB_NAME=stock_data

If ALPHA_VANTAGE_API_KEY is empty, alpha_vantage_overview simply reports that the feature is disabled.

macOS users sometimes hit SSL errors while installing packages. If that happens, run pip install certifi and the server will pick it up automatically.

Run the server

This project runs as an MCP stdio server. The client starts it; you normally do not run it manually unless testing.

python3 server.py

MCP client configuration

ZCode

Add this to ~/.zcode/cli/config.json:

{
  "mcp": {
    "servers": {
      "stock_market_mcp": {
        "command": "python3",
        "args": ["/absolute/path/to/stock_market_mcp/server.py"]
      }
    }
  }
}

Claude Desktop

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "stock_market_mcp": {
      "command": "python3",
      "args": ["/absolute/path/to/stock_market_mcp/server.py"]
    }
  }
}

Use absolute paths. Start a new session after adding the server.

Verify the connection

python3 - <<'EOF'
import asyncio, json
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    params = StdioServerParameters(command="python3", args=["server.py"])
    async with stdio_client(params) as (r, w):
        async with ClientSession(r, w) as s:
            await s.initialize()
            tools = await s.list_tools()
            prompts = await s.list_prompts()
            print("TOOLS:", [t.name for t in tools.tools])
            print("PROMPTS:", [p.name for p in prompts.prompts])

asyncio.run(main())
EOF

Expected result: 20 tool names plus bull_bear_debate.

Example prompts

• "Analyze my watchlist and tell me which stocks to consider buying"

• "Do a technical analysis of TCS.NS"

• "Compare RELIANCE.NS, HDFCBANK.NS and INFY.NS"

• "What is moving in the market today?"

• "Screen for quality value stocks with P/E under 25 and RSI between 40 and 70"

• "How does AAPL correlate with the S&P 500?"

Troubleshooting

Repository layout

stock_market_mcp/
├── app.py                  # Shared FastMCP instance
├── backtest.py             # Backtest harness for the scoring model
├── config.py               # .env loading and runtime config
├── e2e_test.py             # MCP handshake validation
├── prompts/
│   └── debate.py           # bull_bear_debate prompt
├── requirements.txt        # Project dependencies
├── server.py               # Entrypoint: imports all modules and runs MCP stdio
├── tools/
│   ├── __init__.py
│   ├── analysis.py         # analyze_stock, analyze_watchlist, compare_stocks
│   ├── classification.py   # sector_mapping
│   ├── core.py             # quote, search, technicals, alpha vantage overview
│   ├── derivatives.py      # options_data
│   ├── flows.py            # fii_dii_flows
│   ├── fundamentals.py     # currency_impact, dividend_calendar
│   ├── journal.py          # log_decision, review_decisions, analyst_reports
│   ├── market.py           # market_movers, stock_news, earnings_calendar
│   └── screening.py        # stock_screener, correlation_analysis
├── utils/
│   ├── __init__.py
│   └── helpers.py          # _safe, RSI, MACD, Alpha Vantage helpers
├── wiki/                   # GitHub wiki pages
├── .gitignore
├── README.md
└── SESSION_NOTES.md

Backtesting

backtest.py replays the scoring rules over recent market history and compares the signal against benchmark returns. The current findings are intentionally conservative: the technical score can have some short-horizon edge, but the rules are a screening aid rather than a proven predictive model.

Acknowledgements

This project borrows the “grounded analyst reports → bull/bear debate → risk check → decision journal” workflow from TradingAgents and adapts it to an MCP server for NSE/BSE and US markets. The key difference is that the server handles the data retrieval and the client does the higher-level reasoning.

Disclaimer

All output is educational analysis based on public market data and is not financial advice. BUY/HOLD/SELL recommendations are screening aids, not trade recommendations. Always do your own research and consult a qualified financial advisor before investing.

License

MIT