Stock Research Server

Production-grade MCP server for stock intelligence with:

• Alpha Vantage + Finnhub provider fallback
• Deterministic indicators/metrics/scoring
• Claude narrative analysis constrained to computed data
• Dual MCP transport modes: stdio (Claude Desktop local) and http with selectable SSE/streamable endpoints (Render)

File Tree

mcp_server/
├── main.py
├── tools/
│   └── stock_tools.py
├── providers/
│   ├── base.py
│   ├── alpha_vantage.py
│   ├── finnhub.py
│   └── router.py
├── scoring/
│   └── engine.py
├── indicators/
│   └── technical.py
├── analysis/
│   ├── metrics.py
│   ├── signal_engine.py
│   └── claude_engine.py
├── schemas/
│   └── models.py
├── config/
│   └── settings.py
└── utils/
    ├── logging.py
    └── http.py

tests/
├── test_indicators.py
├── test_metrics.py
└── test_scoring.py

Requirements

• Python 3.11+
• API keys:
  • CLAUDE_API_KEY
  • ALPHA_VANTAGE_API_KEY
  • FINNHUB_API_KEY

Setup

python -m venv .venv
. .venv/Scripts/activate
pip install -r requirements.txt
copy .env.example .env

Run (Claude Desktop local via stdio)

Set in .env:

TRANSPORT_MODE=stdio

Run:

python -m mcp_server.main

Run (Render remote via HTTP)

Set in .env:

TRANSPORT_MODE=http
HTTP_TRANSPORT=sse  # or streamable
HOST=0.0.0.0
PORT=8000

Run:

python -m mcp_server.main

Tools

• Existing research/report tools:
  • stock_research_report (primary)
  • analyze_stock
  • get_price
  • get_ohlcv
  • get_technicals
  • get_fundamentals
  • get_news_sentiment
• Trading-style tools:
  • get_stock_price
  • get_quote
  • get_company_profile
  • get_candles
  • get_stock_news
  • get_rsi
  • get_macd
  • get_key_financials

Tests

pytest -q

Render Deployment

1. Push repo to GitHub.
2. Create a Render Web Service.
3. Build command:
   • pip install -r requirements.txt
4. Start command:
   • python -m mcp_server.main
5. Environment variables:
   • TRANSPORT_MODE=http
   • HTTP_TRANSPORT=sse (or streamable)
   • HOST=0.0.0.0
   • PORT=8000
   • CLAUDE_API_KEY, ALPHA_VANTAGE_API_KEY, FINNHUB_API_KEY
6. MCP endpoints:
   • SSE mode (HTTP_TRANSPORT=sse):
     • https://<render-service-domain>/sse
     • https://<render-service-domain>/messages/ (POST)
   • Streamable mode (HTTP_TRANSPORT=streamable):
     • https://<render-service-domain>/mcp
7. Optional health check endpoint:
   • https://<render-service-domain>/health

Claude Desktop Config (local stdio)

Example MCP server entry:

{
  "mcpServers": {
    "stock-research": {
      "command": "python",
      "args": ["-m", "mcp_server.main"],
      "env": {
        "TRANSPORT_MODE": "stdio",
        "CLAUDE_API_KEY": "YOUR_KEY",
        "ALPHA_VANTAGE_API_KEY": "YOUR_KEY",
        "FINNHUB_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Transport Notes

• TRANSPORT_MODE=auto (default) auto-selects:
  • http when hosted (PORT or RENDER env present)
  • stdio locally
• HTTP_TRANSPORT=sse uses:
  • GET /sse
  • POST /messages/
• HTTP_TRANSPORT=streamable uses:
  • POST /mcp