Metadata-Version: 2.4
Name: market-data-mcp
Version: 1.0.0
Summary: MCP server providing real-time financial market data — stock quotes, crypto prices, technicals, sentiment, and more. No API keys required.
Project-URL: Homepage, https://github.com/SmashToes/market-data-mcp
Project-URL: Documentation, https://github.com/SmashToes/market-data-mcp#readme
Project-URL: Repository, https://github.com/SmashToes/market-data-mcp
Project-URL: Issues, https://github.com/SmashToes/market-data-mcp/issues
Project-URL: Changelog, https://github.com/SmashToes/market-data-mcp/releases
Author: Nathan
Maintainer: Nathan
License: MIT
License-File: LICENSE
Keywords: ai-tools,claude,coingecko,crypto,fda,finance,market-data,mcp,model-context-protocol,screener,stocks,technical-analysis,trading,tradingview,yfinance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: tvscreener>=0.1.0
Requires-Dist: yfinance>=0.2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <h1 align="center">Market Data MCP Server</h1>
  <p align="center">
    Real-time financial market data for any MCP-compatible AI assistant.<br/>
    Stocks, crypto, technicals, sentiment, and catalysts — no API keys required.
  </p>
</p>

<p align="center">
  <a href="https://www.python.org/downloads/"><img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white" /></a>
  <a href="https://modelcontextprotocol.io"><img alt="MCP" src="https://img.shields.io/badge/MCP-compatible-green?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJ3aGl0ZSI+PHBhdGggZD0iTTEyIDJMMyA3djEwbDkgNSA5LTVWN2wtOS01em0wIDIuMThMMTggNy41djlsLTYgMy4zMy02LTMuMzN2LTlMMTIgNC4xOHoiLz48L3N2Zz4=" /></a>
  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-yellow" /></a>
</p>

---

## Demo

<!-- Replace with an actual recording using a tool like asciinema or screen capture -->
> **Coming soon:** A GIF showing the server in action with Claude Desktop.
>
> In the meantime, check out the [Example Output](#example-output) section below.

---

## Features

- **11 financial tools** covering equities, crypto, screening, macro, and biotech catalysts
- **Zero configuration** — no API keys, no accounts, no environment variables
- **Three transports** — stdio (Claude Desktop), SSE, and Streamable HTTP
- **Robust error handling** — every tool returns structured JSON, even on failure
- **Built-in fallbacks** — Fear & Greed index degrades gracefully to a VIX-based proxy
- **Production-quality code** — type hints, docstrings, logging, and clean architecture

---

## Quick Start

### 1. Clone the repository

```bash
git clone https://github.com/SmashToes/market-data-mcp.git
cd market-data-mcp
```

### 2. Install dependencies

```bash
pip install -e .
```

### 3. Run the server

```bash
# For Claude Desktop (stdio transport — the default)
python server.py

# For network access (SSE on port 8100)
python server.py --transport sse --port 8100

# For network access (Streamable HTTP on port 8100)
python server.py --transport streamable-http --port 8100
```

That's it. No `.env` file, no API keys, no configuration.

---

## Tool Reference

| Tool | Parameters | Description |
|------|-----------|-------------|
| `get_stock_quote` | `ticker` (str) | Real-time stock price, change, volume, market cap, PE ratio, 52-week range, sector |
| `get_crypto_price` | `symbol` (str) | Cryptocurrency price via CoinGecko with 24h/7d/30d changes, market cap, ATH distance |
| `get_market_movers` | *none* | Today's top 10 gainers and losers from a universe of 60+ liquid stocks |
| `get_sector_performance` | *none* | All 11 S&P 500 sector ETFs with 1-day, 5-day, and 1-month returns |
| `get_earnings_calendar` | `days_ahead` (int, default 7) | Upcoming earnings reports with EPS and revenue estimates |
| `get_technical_indicators` | `ticker` (str) | RSI, MACD, SMA (20/50/200), EMA, Bollinger Bands, volume analysis, signal interpretation |
| `get_fear_greed_index` | *none* | CNN Fear & Greed Index (0-100) with historical comparison and VIX fallback |
| `get_fda_calendar` | *none* | Upcoming FDA PDUFA drug approval dates — major biotech catalysts |
| `screen_stocks` | `market`, `sector`, `min_price`, `max_price`, `min_volume`, `min_market_cap`, `sort_by`, `limit` | TradingView stock screener with filters for market, sector, price, volume, and technicals |
| `screen_crypto` | `min_volume`, `min_market_cap`, `sort_by`, `limit` | TradingView crypto screener with market cap filtering to exclude DEX noise |
| `top_movers` | `market`, `min_price`, `min_volume`, `count` | Market-wide top gainers, losers, and most active via TradingView screener engine |

---

## Example Output

### Stock Quote

```
> get_stock_quote("NVDA")
```

```json
{
  "ticker": "NVDA",
  "name": "NVIDIA Corporation",
  "price": 131.28,
  "change": 3.45,
  "change_percent": "+2.70%",
  "volume": "312.5M",
  "market_cap": "3.22T",
  "pe_ratio": 64.12,
  "52w_high": 153.13,
  "52w_low": 47.32,
  "sector": "Technology"
}
```

### Technical Indicators

```
> get_technical_indicators("AAPL")
```

```json
{
  "ticker": "AAPL",
  "price": 232.15,
  "rsi_14": 58.4,
  "rsi_signal": "Neutral",
  "macd": {
    "macd_line": 1.2834,
    "signal_line": 0.9621,
    "histogram": 0.3213
  },
  "bollinger_bands": {
    "upper": 238.50,
    "middle": 229.30,
    "lower": 220.10
  },
  "signals": [
    "RSI Neutral (58.4)",
    "MACD bullish",
    "Golden Cross (SMA 50 > 200)"
  ]
}
```

### Fear & Greed Index

```
> get_fear_greed_index()
```

```json
{
  "score": 38,
  "rating": "Fear",
  "classification": "Fear",
  "previous_close": 35,
  "one_week_ago": 29,
  "one_month_ago": 52
}
```

---

## Use with Claude Desktop

Add the following to your Claude Desktop configuration file:

| Platform | Config Location |
|----------|----------------|
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |

```json
{
  "mcpServers": {
    "market-data": {
      "command": "python",
      "args": ["/absolute/path/to/market-data-mcp/server.py"],
      "env": {}
    }
  }
}
```

Restart Claude Desktop. The tools icon (hammer) will appear in the chat input area, confirming the server is connected.

### Use with Claude Code (CLI)

```bash
claude mcp add market-data -- python /path/to/market-data-mcp/server.py
```

Or connect to a running network server:

```bash
claude mcp add market-data --transport sse http://localhost:8100/sse
```

---

## Example Prompts

Once connected, try asking Claude:

- *"What's the current price of NVDA?"*
- *"Show me the top market movers today"*
- *"Give me technical analysis on AAPL"*
- *"What's the Fear & Greed index right now?"*
- *"Which sectors are performing best this week?"*
- *"What earnings are coming up in the next 14 days?"*
- *"Show me the price of Bitcoin and Solana"*
- *"Any upcoming FDA approval dates for biotech stocks?"*
- *"Screen for healthcare stocks with volume over 1M"*
- *"What are the top crypto gainers right now?"*
- *"Show me the biggest stock losers in the US market today"*

---

## Architecture

```
market-data-mcp/
├── server.py              # MCP server — all 11 tools in a single file
├── demo.py                # Standalone demo (no MCP client needed)
├── pyproject.toml          # Package metadata and dependencies
├── data/
│   └── fda_calendar.json   # Curated FDA PDUFA dates
├── .github/
│   └── FUNDING.yml         # Sponsor configuration
├── LICENSE                 # MIT License
├── .gitignore
└── README.md
```

### Design Decisions

- **Single-file server.** All tools live in `server.py` for maximum portability. Clone, install, run — no package structure to navigate.
- **No API keys.** Every data source is free and public. yfinance (Yahoo Finance), CoinGecko free tier, CNN public endpoint, and a bundled JSON file for FDA dates.
- **Graceful degradation.** If the CNN Fear & Greed endpoint is down, the tool automatically falls back to a VIX-based proxy score. If a stock ticker is invalid, the tool returns a structured error — never an exception.
- **Read-only annotations.** Every tool is annotated with `readOnlyHint=true`, signaling to MCP clients that these tools have no side effects and are safe to call without user confirmation.

### Data Sources

| Source | Used For | Rate Limits |
|--------|----------|-------------|
| [yfinance](https://github.com/ranaroussi/yfinance) | Stocks, ETFs, earnings, technicals | Generous (Yahoo Finance) |
| [CoinGecko API](https://www.coingecko.com/en/api) | Cryptocurrency prices | 10-30 req/min (free tier) |
| [tvscreener](https://github.com/shner-elmo/TradingView-Screener) | Stock & crypto screening | TradingView screener API |
| [CNN Fear & Greed](https://edition.cnn.com/markets/fear-and-greed) | Market sentiment | Public endpoint |
| Bundled JSON | FDA PDUFA calendar | No limits (local file) |

---

## Updating the FDA Calendar

The FDA calendar lives in `data/fda_calendar.json`. Each entry follows this schema:

```json
{
  "ticker": "VKTX",
  "company": "Viking Therapeutics",
  "drug": "VK2735",
  "indication": "Obesity",
  "pdufa_date": "2026-03-15",
  "catalyst_type": "Phase 3 Data",
  "notes": "Oral obesity candidate"
}
```

Add or remove entries as new PDUFA dates are announced.

---

## Contributing

Contributions are welcome. Here's how to get started:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/add-options-flow`)
3. Make your changes
4. Test with Claude Desktop or the standalone `demo.py`
5. Submit a pull request

### Ideas for Contribution

- **New tools:** Options flow, insider trading activity, IPO calendar, economic indicators
- **Data sources:** Alpha Vantage, Polygon.io, or FRED for macroeconomic data
- **Caching layer:** Add TTL-based caching to reduce API calls for repeated queries
- **Docker support:** Containerize the SSE/HTTP server for cloud deployment

---

## Requirements

- Python 3.10+
- Internet connection (for live market data)
- No API keys needed

---

## License

[MIT](LICENSE) -- Copyright 2026 Nathan
