Skip to main content
Glama
pforpav

Stock Snapshot MCP

by pforpav
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

📈 Stock Snapshot MCP

Python MCP AlphaVantage Claude Status License PyPI

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

Related MCP server: AlphaVantage-MCP

⚙️ 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

  1. Sends the snapshot JSON to Claude

  2. 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.

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/pforpav/stock-snapshot-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server