market-data-mcp

Real-time market data: quotes, news, earnings calendar, and a watchlist scanner for AI agents — backed by Finnhub.

Gives any MCP client (Claude Desktop, Claude Code, agents) clean, uniform market data tools that fail gracefully. A missing or premium-gated source returns "no data", never a fabricated value. Markdown output by default, JSON on demand.

Tools

*Calendar tested live on 2026-06-14: accessible on Finnhub free tier.
**broker_positions requires ALPACA_API_KEY + ALPACA_SECRET_KEY in .env. Degrades gracefully without them.

Every tool returns Markdown (human-readable, default) or JSON (response_format="json") for programmatic use.

Related MCP server: MonteWalk

Live demo output (2026-06-14)

market_quote AAPL:
  AAPL: $291.13  (-1.52%  -$4.50)  prev close $295.63

market_scan AAPL,MSFT,NVDA,TSLA:
  Scanned 4/4 symbols. Top mover: TSLA +1.82%

market_calendar days=7:
  20 earnings events in the next 7 days: ACN, KR, MEI ...

market_analyze AAPL:
  Signal: Lean negative  [......##|........] -30/100  confidence 60%
  AAPL: $291.13  -1.52%  → Lean negative [TRIM]
  Catalyst: Apple's iOS 27 surprise could change the AI narrative

Quick start

git clone <your-repo-url> market-data-mcp
cd market-data-mcp
python -m venv .venv
.venv\Scripts\activate        # Windows
pip install -r requirements.txt

copy .env.example .env        # edit: add FINNHUB_API_KEY
python tests/test_smoke.py    # live test all 6 tools

Get a free Finnhub key at: https://finnhub.io/register

Claude Desktop config

Add this to claude_desktop_config.json (%APPDATA%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS), then restart Claude Desktop:

{
  "mcpServers": {
    "market-data-mcp": {
      "command": "python",
      "args": ["-m", "market_data_mcp"],
      "cwd": "C:/path/to/market-data-mcp"
    }
  }
}

Use the system Python path if you are not using a venv:

{
  "mcpServers": {
    "market-data-mcp": {
      "command": "C:/Users/YourName/AppData/Local/Python/pythoncore-3.14-64/python.exe",
      "args": ["-m", "market_data_mcp"],
      "cwd": "C:/path/to/market-data-mcp",
      "env": { "PYTHONUTF8": "1" }
    }
  }
}

Optional: Alpaca broker source

The broker_positions tool reads your Alpaca paper account. To enable it:

1. Go to https://app.alpaca.markets/ → Paper Trading → API Keys

2. Add to .env:

   ALPACA_API_KEY=your-key-here
   ALPACA_SECRET_KEY=your-secret-here

3. Restart the server.

Without these keys, broker_positions returns a graceful "keys not set" message.

Why it's built this way

• Uniform result contract. Every source returns the same Result shape (source, ok, summary, data, score, confidence, error). An LLM can reason across all tools without parsing N formats.

• Graceful degradation. A source with no data, a premium-gated endpoint, or a missing key returns Result.failed(...) — never a fabricated value. Zero-price from Finnhub for unknown symbols is treated as "no data", not a quote.

• Scored analysis. The composite market_analyze tool emits a -100..+100 directional score with confidence, so an agent can triage without reading prose.

• TTL cache. Per-source in-process cache avoids hammering rate-limited APIs when an agent calls several tools in one turn (e.g. scan + analyze in sequence).

Disclaimer

For research and educational use only. Data comes from Finnhub and Alpaca and may be delayed or incomplete. Never use automated market data for financial decisions without independent verification.

License

MIT