Skip to main content
Glama
Sign In
Stock Snapshot MCP

Stock Snapshot MCP

by pforpav
OverviewSchemaSourceRelated ServersDiscussionsAdmin
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.

Available Tools

1 tool
get_stock_snapshotA

Return a stock snapshot from Alpha Vantage, including meta info, latest quote, basic fundamentals (if available), and recent daily OHLCV history. Educational / demo use only.

Inputs: symbol (required), history_days.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4/5.0

    Scored across 1 tool

    Disambiguation5/5

    Only one tool exists, so no risk of confusion or overlap with other tools.

    Naming Consistency5/5

    The single tool name 'get_stock_snapshot' follows a clear verb_noun pattern.

    Tool Count3/5

    One tool is minimal for a stock snapshot server; for educational/demo use it may suffice, but typically more tools are expected.

    Completeness3/5

    The tool covers a snapshot request, but lacks separate endpoints for history, search, or detailed fundamentals, leaving gaps for typical stock data needs.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • findata-mcp-server

      xBlueCode
      A
      license
      B
      quality
      D
      maintenance
      This is an MCP server that provides access to the Alpha Vantage API, allowing stock data retrieval to be used as context to LLMs.
      2
      45 npm
      9
      MIT

    • AlphaVantage-MCP

      berlinbra
      A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server that provides real-time access to financial market data through the free Alpha Vantage API. This server implements a standardized interface for retrieving stock quotes and company information.
      12
      104
      MIT

    • Stock Market MCP Server

      MCP-100
      F
      license
      B
      quality
      D
      maintenance
      A TypeScript-based MCP server that fetches real-time stock market data and company financial information through the Alpha Vantage API.
      4
      6
      -