# 📈 Stock Snapshot MCP  
![Python](https://img.shields.io/badge/Python-3.10%2B-blue?style=for-the-badge&logo=python)
![MCP](https://img.shields.io/badge/MCP-Server-8A2BE2?style=for-the-badge)
![AlphaVantage](https://img.shields.io/badge/Alpha%20Vantage-API-0A0A23?style=for-the-badge)
![Claude](https://img.shields.io/badge/Claude-4.5%20Sonnet-101010?style=for-the-badge&logo=anthropic)
![Status](https://img.shields.io/badge/Status-Experimental-orange?style=for-the-badge)
![License](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)
[![PyPI](https://img.shields.io/badge/PyPI-stock--snapshot--mcp-blue?style=for-the-badge&logo=pypi)](https://pypi.org/project/stock-snapshot-mcp/)



*A minimal, educational MCP server for stock snapshots using the free Alpha Vantage API.*

**Stock Snapshot MCP** is a tiny, easy-to-read reference implementation of a  
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server.

It exposes a **single, clean tool**:
```get_stock_snapshot(symbol, history_days=60)```


This tool queries the free Alpha Vantage API and returns:

- Company metadata (name, sector, industry, exchange, currency)  
- Latest quote (price, change, percent, previous close, volume)  
- Basic fundamentals (PE ratio, EPS, market cap, ROE, profit margin — if available)  
- Recent OHLCV price history (daily candles)

This project is ideal for:

- People learning MCP through a small, realistic example  
- Developers building **RAG-ready financial research agents**  
- Students who want a simple MCP server to extend or customize  
- Anyone experimenting with Claude / ChatGPT MCP integrations  
- Mini-projects where clean, structured stock data is useful  

> **Note:** This project is *not* affiliated with Alpha Vantage.  
> It is designed solely as an educational reference.  
> **Not for real trading or investment decisions.**

---

## ✨ Features

- 📦 **Lightweight Python package** (`pip install stock-snapshot-mcp`)
- 🔌 **MCP server (stdio)** compatible with Claude Desktop, ChatGPT MCP, and other tools
- 🔍 Clean JSON output suitable for LLM reasoning & agent pipelines

---

## ⚙️ Installation

### **1. Install the package**
```bash
pip install stock-snapshot-mcp
```
### **2. Set your Alpha Vantage API key**

Create a .env file or export it:
```bash
export ALPHAVANTAGE_API_KEY=your_key_here
```
---
## 🗣️ Example: Claude-Powered Stock Analysis Chatbot

This repository includes a simple but powerful example demonstrating how to combine:
- `stock_snapshot_mcp`
- **Claude (Anthropic API)**
- **Alpha Vantage data**

to build a terminal-based stock analysis chatbot:

```bash
examples/claude_stock_chat.py
```

**What this example does**
1. Fetches real market data
```python
from stock_snapshot_mcp import get_stock_snapshot
```
2. Sends the snapshot JSON to Claude
3. Claude returns an educational, non-advisory analysis

**The chatbot enforces strict safety rules:**
- No investment advice 
- No buy/sell/hold language 
- Educational tone only

**Run the chatbot**
```bash
export ANTHROPIC_API_KEY=your_claude_key
export ALPHAVANTAGE_API_KEY=your_alpha_vantage_key

python examples/claude_stock_chat.py
```

**Example interaction:**
```bash
Enter stock symbol: AAPL
What do you want to know? <user input>
```
**Process Flow**
```mermaid
sequenceDiagram
    participant U as User
    participant C as CLI Chat (claude_stock_chat.py)
    participant S as stock_snapshot_mcp
    participant A as Alpha Vantage API
    participant L as Claude (Anthropic API)

    U->>C: Enter ticker (e.g. AAPL) + question
    C->>S: get_stock_snapshot("AAPL", history_days=60)
    S->>A: HTTP request for quote, fundamentals, daily prices
    A-->>S: JSON responses (quote, overview, time series)
    S-->>C: Normalized snapshot dict (meta, quote, fundamentals, history)

    C->>L: Snapshot JSON + user question in prompt
    L-->>C: Educational explanation (no investment advice)

    C-->>U: Print explanation in terminal
```

---

## 🚀 Running the MCP server

### 🧪 Testing locally (Python)

You can call the helper function directly:
```python
from stock_snapshot_mcp import get_stock_snapshot
import asyncio

async def main():
    snap = await get_stock_snapshot("AAPL", history_days=5)
    print(snap)

asyncio.run(main())
```

### 🧪 Example: manual MCP client

For debugging or learning MCP, you can run:

```bash
python examples/manual_mcp_client.py
````

### 🖥️ Using with Claude Desktop (example config)

Place this inside Claude’s configuration file:

**macOS**

`~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**

`%APPDATA%\Claude\claude_desktop_config.json`

Add:
```json
{
  "mcpServers": {
    "stock-snapshot-mcp": {
      "command": "stock-snapshot-mcp",
      "env": {
        "ALPHAVANTAGE_API_KEY": "your_key_here"
      }
    }
  }
}
```

Restart Claude Desktop → you should see Stock Snapshot MCP under "Connected Servers".

Then you can ask Claude:

> Call `get_stock_snapshot` for AAPL and summarize the fundamentals.


### 📤 Using with ChatGPT MCP (OpenAI Desktop / browser)

Add a new MCP connection:
- Command: `stock-snapshot-mcp`
- Environment:
  - `ALPHAVANTAGE_API_KEY=your_key_here`
And that’s it.

---

## 📚 Tool Definition (JSON Schema)

```php
get_stock_snapshot(
  symbol: string (required),
  history_days: integer (optional, 1–100, default: 60)
)
```

Output fields
```css
{
  "symbol": "AAPL",
  "meta": {
    "name": "Apple Inc",
    "sector": "TECHNOLOGY",
    "industry": "CONSUMER ELECTRONICS",
    "currency": "USD",
    "exchange": "NASDAQ"
  },
  "quote": {
    "price": 278.78,
    "change": -1.92,
    "change_percent": -0.684,
    "previous_close": 280.7,
    "latest_trading_day": "2025-12-05",
    "volume": 47265845
  },
  "fundamentals": {
    "market_cap": 4137203794000,
    "pe_ratio_ttm": 37.32,
    "eps_ttm": 7.47,
    "roe_ttm": 1.714,
    "profit_margin": 0.269
  },
  "daily_history": [ ... ]
}
```

---

## 🧱 Project Structure
```pgsql
stock-snapshot-mcp/
│
├── dist/                              # Built distributions (wheel + sdist)
│   ├── stock_snapshot_mcp-0.1.0.tar.gz
│   └── stock_snapshot_mcp-0.1.0-py3-none-any.whl
│
├── examples/
│   └── manual_mcp_client.py           # Human-readable demo MCP client
│
├── src/
│   ├── stock_snapshot_mcp/            # Actual Python package 
│   │   ├── __init__.py
│   │   ├── alpha_vantage_client.py    # Async Alpha Vantage helper functions
│   │   └── server.py                  # MCP stdio server entrypoint
│   │
│   └── stock_snapshot_mcp.egg-info/   # Metadata created after build
│
├── tests/
│   ├── test_alpha_vantage_client.py   # Integration test for API wrapper
│   └── test_mcp_server.py             # Full MCP stdio server end-to-end test
│
├── LICENSE
├── pyproject.toml                     # Package config (build + metadata)
└── README.md

 ```

---

## 🛑 Disclaimer

This project:

- is not affiliated with Alpha Vantage 
- is not financial advice 
- is provided for educational and research purposes only

---

## 📜 License

MIT License — free to use, modify, and learn from.