# Stock MCP Server

An MCP (Model Context Protocol) server that gives Claude access to accurate,
free stock-market data — quotes, fundamentals, history, news, index top-10
rankings, market movers, and penny-stock screens. All data comes from public
sources (Yahoo Finance via `yfinance`, plus Wikipedia/Slickcharts for index
membership). **No API keys, no paid subscriptions.**

## Tools

| Tool | What it does |
|---|---|
| `get_quote` | Current price, day change, volume, market cap, 52-week range for one or more tickers |
| `get_company_info` | Company profile & fundamentals: sector, P/E, margins, dividend, analyst targets |
| `get_price_history` | Historical OHLCV bars (1 day to max, intraday to monthly intervals) |
| `get_top_stocks` | Top N stocks of the **S&P 500, S&P 100, Dow, or Nasdaq-100**, ranked by day performance, worst performers, or market cap |
| `get_market_movers` | Yahoo predefined screens: day gainers, day losers, most actives, small-cap gainers, and more |
| `get_penny_stocks` | Screens US **penny stocks** (share price $0.10–$5) with a volume filter, sorted by day gain |
| `get_stock_news` | Recent news articles (title, publisher, summary, link) for a ticker |
| `search_stocks` | Find tickers by company name or partial symbol |
| `list_index_constituents` | Full membership list of a supported index |

## Run with Docker (recommended)

The server runs as a Streamable HTTP MCP server on **port 8200**:

```powershell
cd "D:\Local Development\Stock MCP Server"
docker compose up -d --build
```

The MCP endpoint is then `http://localhost:8200/mcp`.

- Logs: `docker logs stock-mcp`
- Stop: `docker compose down`
- Change the port: edit `MCP_PORT` and the `ports` mapping in
  `docker-compose.yml` (host and container side).

## Use with Claude Code

A project-scoped `.mcp.json` is already included and points at the Docker
endpoint (`http://localhost:8200/mcp`) — start the container, open Claude
Code in this directory, and approve the `stock-info` server when prompted.

## Use with Claude Desktop

Add this to `%APPDATA%\Claude\claude_desktop_config.json` under
`"mcpServers"` (with the container running):

```json
{
  "mcpServers": {
    "stock-info": {
      "type": "http",
      "url": "http://localhost:8200/mcp"
    }
  }
}
```

Then restart Claude Desktop. (If your Claude Desktop version doesn't support
HTTP servers directly, use the stdio setup below instead.)

## Run without Docker (stdio, local)

```powershell
cd "D:\Local Development\Stock MCP Server"
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

# Run on stdio (default transport)
.\.venv\Scripts\python.exe server.py
```

Stdio Claude Desktop config:

```json
{
  "mcpServers": {
    "stock-info": {
      "command": "D:\\Local Development\\Stock MCP Server\\.venv\\Scripts\\python.exe",
      "args": ["D:\\Local Development\\Stock MCP Server\\server.py"]
    }
  }
}
```

Environment variables: `MCP_TRANSPORT` (`stdio` default, or
`streamable-http`), `MCP_HOST` (default `0.0.0.0`), `MCP_PORT`
(default `8200`).

## Notes & limitations

- Data is sourced from Yahoo Finance's public endpoints via the `yfinance`
  library. It is delayed/indicative, subject to Yahoo's rate limits, and not
  suitable for trading execution. This server provides **information only,
  not investment advice**.
- Index constituent lists are scraped from Wikipedia (S&P 500/100, Dow) and
  Slickcharts (Nasdaq-100) and cached for 24 hours. If a page layout changes,
  `get_top_stocks` / `list_index_constituents` may need a source update in
  `INDEX_SOURCES` in `server.py`.
- `get_top_stocks` with `rank_by="market_cap"` makes one lightweight request
  per constituent (threaded), so the S&P 500 takes ~15–30 seconds; the
  S&P 100 and Dow are fast.