Skip to main content
Glama
pforpav

Stock Snapshot MCP

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

ParametersJSON Schema
NameRequiredDescriptionDefault
symbolYesTicker symbol, e.g. AAPL, MSFT, TSLA
history_daysNoNumber of most recent daily candles to return (max ~100).

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses data source (Alpha Vantage) and content (last quote, fundamentals, OHLCV), but omits rate limits, data freshness, or error behavior. Adequate for a simple read tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first states purpose and content, second adds usage note. No redundant words, front-loaded, highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately lists return elements (meta, quote, fundamentals, OHLCV). Lacks details on response format but sufficient for a simple snapshot. No critical gaps identified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so schema already describes both parameters (symbol and history_days). Description does not add extra parameter meaning beyond the usage disclaimer.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool returns a stock snapshot from Alpha Vantage, including specific data types (meta info, quote, fundamentals, OHLCV). Verb 'Return' and resource are explicit, and there are no sibling tools to differentiate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes a clear usage constraint: 'Educational / demo use only.' This implies when to use and cautions against production use, though no explicit alternative tools are mentioned (none provided).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev0.1.0
    • First observedget_stock_snapshot
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
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 issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

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

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
    29
    9
    MIT

  • AlphaVantage-MCP

    berlinbra
    A
    license
    B
    quality
    F
    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
    -

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