📈 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) 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

pip install stock-snapshot-mcp

2. Set your Alpha Vantage API key

Create a .env file or export it:

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:

examples/claude_stock_chat.py

What this example does

1. Fetches real market data

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

export ANTHROPIC_API_KEY=your_claude_key
export ALPHAVANTAGE_API_KEY=your_alpha_vantage_key

python examples/claude_stock_chat.py

Example interaction:

Enter stock symbol: AAPL
What do you want to know? <user input>

Process Flow

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:

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:

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:

{
  "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)

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

Output fields

{
  "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

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.