🧠 stock_market_mcp

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

A Model Context Protocol (MCP) server that analyzes stocks and returns a scored BUY / HOLD / SELL assessment, so you can ask your AI client "which stocks should I look at?" and get data-backed answers.

Works for the Indian market (NSE/BSE) and US market out of the box.

📖 Full documentation: the wiki — setup, tools reference, architecture, backtesting and FAQ.

APIs used

Alpha Vantage free-tier notes (verified live): the free key is rate-limited to ~25 requests/day, 1 request/sec — exceeding it returns an "Information" notice instead of data. Also, Alpha Vantage's OVERVIEW endpoint works for US symbols (e.g. AAPL ✔) but returns empty data for NSE/BSE symbols (RELIANCE.BSE ✘) — Indian-market coverage comes entirely from Yahoo Finance, which is why Yahoo is the primary source.

Tools

Prompts

Decision journal

Every log_decision call is stored in MongoDB (stock_data.decision_journal, configurable via MONGODB_URI/MONGODB_DB_NAME). If MongoDB is unreachable, the journal automatically falls back to a local decision_journal.json. review_decisions closes the loop: it prices each open decision and marks the outcome CORRECT / WRONG / NEUTRAL — so recommendations are measured, not forgotten.

Grounded data snapshots

analyze_stock and analyst_reports embed a timestamped data_snapshot — every indicator value the score is computed from, with its source. Follows the TradingAgents principle that analysis claims must trace to a verified data snapshot, never LLM memory.

Symbol formats

Setup

Prerequisites

• Python 3.10+ (tested on 3.13)

• pip

• An MCP client (ZCode, Claude Desktop, or any MCP-compatible client)

• (Optional) Alpha Vantage API key

1. Get the code

git clone https://github.com/AnupamSinha/stock_market_mcp.git
cd stock_market_mcp

2. Install dependencies

pip install -r requirements.txt

This installs mcp (the MCP SDK) and yfinance.

macOS note: if HTTPS calls fail with an SSL certificate error, run pip install certifi. The server already uses certifi automatically when present.

3. Configure the Alpha Vantage key (optional)

Create a .env file in the project root (or export an env var). The server loads .env automatically at startup — existing environment variables take precedence:

# .env
ALPHA_VANTAGE_API_KEY=your_key_here
ALPHA_VANTAGE_BASE_URL=https://www.alphavantage.co/query

All other tools work with no configuration at all.

Run

python3 server.py

The server runs on stdio — it's not a web server; an MCP client launches it and talks to it over stdin/stdout. You normally don't run it by hand; the client config below does it for you.

Configure your MCP client

ZCode

Add to ~/.zcode/cli/config.json (user scope — available in every workspace):

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

Restart ZCode (or start a new session) — the tools appear as mcp__stock_market_mcp__* and connect automatically.

Claude Desktop

Edit the config file:

• 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"]
    }
  }
}

Restart Claude Desktop and start a new conversation — the tools icon (hammer) should show the stock tools.

Use absolute paths in both configs. If python3 isn't found, use the full path (which python3 to find it).

Verify it works

Run an end-to-end test with a real MCP client handshake:

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()
            print("TOOLS:", [t.name for t in tools.tools])
            res = await s.call_tool("analyze_watchlist", {"symbols": "RELIANCE.NS,ITC.NS"})
            print(json.loads(res.content[0].text)["ranked"])

asyncio.run(main())
EOF

Expected output: the 8 tool names and a ranked list with scores and recommendations.

Example prompts (once connected)

• "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's the latest news on INFY.NS?"

• "Analyze AAPL and MSFT and tell me which looks better"

Troubleshooting

Project structure

stock_market_mcp/
├── server.py                 # The MCP server (FastMCP, stdio transport)
├── backtest.py               # Backtest harness for the scoring rules (5y NSE, monthly)
├── requirements.txt          # mcp, yfinance
├── .env                      # Optional: ALPHA_VANTAGE_API_KEY (never committed)
├── decision_journal.json     # Journal fallback when MongoDB is down (never committed)
├── .gitignore
└── README.md

Backtesting

backtest.py replays the technical half of the scoring rules over ~5 years of NIFTY-100 price history, month by month, and measures forward 1/3/6/12-month returns by score bucket and quintile against the NIFTY 50 benchmark:

python3 backtest.py

Findings so far (see the script header for limitations): the technical score has modest short-horizon (1–3 month) ranking power; BUY and HOLD levels are indistinguishable at longer horizons; the SELL cutoff never triggers on the technical-only score. Treat the scoring weights as tunable, not settled.

Acknowledgements

The multi-agent workflow shape — grounded analyst reports, bull-vs-bear debate, risk check, decision journal with outcome review — is inspired by TauricResearch/TradingAgents (Apache-2.0), re-implemented here as a lightweight, India-focused (NSE/BSE) MCP server. Thanks to the TradingAgents team for open-sourcing the ideas.

About FoodForBrains

FoodForBrains builds tools that make market information digestible — analysis you can actually reason about, with every number traceable to its source. This project is part of that mission: grounded data in, transparent reasoning out.

Disclaimer

All output is educational analysis generated from public market data — it is not financial advice. The BUY/HOLD/SELL scores are a screening aid based on simple technical and fundamental rules; do your own research and consult a financial advisor before investing.

License

MIT