cstamigo-droid/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
| Tool | What it does | Source | Free tier |
| marketquote | Real-time price, % change, high/low/open/prev-close | Finnhub /quote | Yes |
| marketnews | Top 5 headlines — company-specific or general market | Finnhub /company-news, /news | Yes |
| marketcalendar | Earnings calendar for the next N days (with EPS/revenue estimates) | Finnhub /calendar/earnings | Yes |
| marketscan | Watchlist scanner: rank up to 25 tickers by absolute % change | Finnhub /quote x N | Yes |
| marketanalyze | Composite: momentum score + news catalyst + earnings proximity | All of the above | Yes |
| brokerpositions | Read open positions from Alpaca paper account | Alpaca Paper API | Optional |
Calendar tested live on 2026-06-14: accessible on Finnhub free tier.
brokerpositions requires ALPACAAPIKEY + ALPACASECRETKEY in .env. Degrades gracefully without them.
Every tool returns Markdown (human-readable, default) or JSON (responseformat="json") for programmatic use.
## Live demo output (2026-06-14)
marketquote AAPL:
AAPL: $291.13 (-1.52% -$4.50) prev close $295.63
marketscan AAPL,MSFT,NVDA,TSLA:
Scanned 4/4 symbols. Top mover: TSLA +1.82%
marketcalendar days=7:
20 earnings events in the next 7 days: ACN, KR, MEI ...
marketanalyze 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
> Note: the market-data-mcp package on PyPI is a different, unrelated
> project by another author. Install this one from source:
bash
git clone https://github.com/cstamigo-droid/market-data-mcp.git
cd market-data-mcp
python -m venv .venv
.venv\Scripts\activate # Windows
pip install -r requirements.txt
copy .env.example .env # edit: add FINNHUBAPIKEY
python tests/testsmoke.py # live test all 6 tools
Get a free Finnhub key at: https://finnhub.io/register
## Claude Desktop config
Add this to claudedesktopconfig.json
(%APPDATA%\Claude\ on Windows, ~/Library/Application Support/Claude/ on macOS),
then restart Claude Desktop:
json
"mcpServers": {
"market-data-mcp": {
"command": "python",
"args": ["-m", "marketdatamcp"],
"cwd": "C:/path/to/market-data-mcp"
Use the system Python path if you are not using a venv:
json
"mcpServers": {
"market-data-mcp": {
"command": "C:/Users/YourName/AppData/Local/Python/pythoncore-3.14-64/python.exe",
"args": ["-m", "marketdatamcp"],
"cwd": "C:/path/to/market-data-mcp",
"env": { "PYTHONUTF8": "1" }
## Optional: Alpaca broker source
The brokerpositions tool reads your Alpaca paper account. To enable it: