✅ Official Alpha Vantage MCP Server

A MCP server for the stock market data API, Alphavantage API.

MCP Server URL: https://mcp.alphavantage.co

PyPi: https://pypi.org/project/alphavantage-mcp/

Configuration

Getting an API Key

1. Sign up for a Free Alphavantage API key

2. Add the API key to your environment variables as ALPHAVANTAGE_API_KEY

Installation

Option 1: Using uvx (Recommended)

The easiest way to use the AlphaVantage MCP server is with uvx:

Option 2: Using pip

Option 3: From source

Server Modes

The AlphaVantage server can run in two different modes:

Stdio Server (Default)

This is the standard MCP server mode used for tools like Claude Desktop.

Streamable HTTP Server

This mode provides real-time updates via HTTP streaming.

Streamable HTTP Server with OAuth 2.1 Authentication

This mode adds OAuth 2.1 authentication to the HTTP server, following the MCP specification for secure access.

OAuth Configuration

When using the --oauth flag, the server requires OAuth 2.1 configuration via environment variables:

Required Environment Variables:

Optional Environment Variables:

OAuth Features

The OAuth implementation provides:

• OAuth 2.0 Protected Resource Metadata endpoint (/.well-known/oauth-protected-resource)

• Bearer token authentication for all MCP requests

• JWT and Token Introspection validation methods

• MCP Security Best Practices compliance:

  • Token audience validation (prevents token passthrough attacks)

  • Session hijacking prevention with secure session IDs

  • User-bound sessions for additional security

  • Proper WWW-Authenticate headers for 401 responses

Example: Keycloak Configuration

For testing with Keycloak:

OAuth Client Flow

When OAuth is enabled, MCP clients must:

1. Discover the authorization server via GET /.well-known/oauth-protected-resource

2. Register with the authorization server (if using Dynamic Client Registration)

3. Obtain access tokens from the authorization server

4. Include tokens in requests: Authorization: Bearer <access-token>

5. Handle 401/403 responses and refresh tokens as needed

Options:

• --server: Choose between stdio (default) or http server mode

• --port: Specify the port for the Streamable HTTP server (default: 8080)

• --oauth: Enable OAuth 2.1 authentication (requires --server http)

📊 Telemetry

The AlphaVantage MCP server includes optional Prometheus metrics for monitoring and observability.

Enabling Telemetry

Set the following environment variables to enable telemetry:

Metrics Endpoint

When telemetry is enabled, Prometheus metrics are available at:

Available Metrics

The server collects the following metrics for each tool call:

• mcp_tool_calls_total - Total number of tool calls (labeled by tool and outcome)

• mcp_tool_latency_seconds - Tool execution latency histogram

• mcp_tool_request_bytes - Request payload size histogram

• mcp_tool_response_bytes - Response payload size histogram

• mcp_tool_active_concurrency - Active concurrent tool calls gauge

• mcp_tool_errors_total - Total errors by type (timeout, bad_input, connection, unknown)

Example Usage with Telemetry

🚀 AWS Serverless Deployment

Deploy the AlphaVantage MCP Server on AWS Lambda using the stateless MCP pattern for production-ready, scalable deployment.

Quick AWS Deployment

Features:

• ✅ Stateless MCP pattern - Perfect for Lambda's execution model

• ✅ Auto-scaling - Handles any load with AWS Lambda + API Gateway

• ✅ Cost-effective - Pay only for requests (~$1-5/month for typical usage)

• ✅ Production-ready - Based on AWS official sample patterns

• ✅ OAuth 2.1 support - Optional authentication for secure access

📖 Full Documentation: See AWS Deployment Guide for complete setup instructions, testing, monitoring, and troubleshooting.

Usage with Claude Desktop

Option 1: Using uvx (Recommended)

Add this to your claude_desktop_config.json:

Option 2: From source

If you cloned the repository, use this configuration:

Running the Server in Streamable HTTP Mode

Using uvx:

From source:

📺 Demo Video

Watch a quick demonstration of the Alpha Vantage MCP Server in action:

🔧 Development & Publishing

Publishing to PyPI

This project includes scripts for publishing to PyPI and TestPyPI:

The script uses twine by default (recommended) but can also use uv publish with the --use-uv flag.

GitHub Actions

The repository includes a GitHub Actions workflow for automated publishing:

• Trusted Publishing: Uses PyPA's official publish action with OpenID Connect

• Manual Trigger: Can be triggered manually with options for TestPyPI vs PyPI

• Twine Fallback: Supports both trusted publishing and twine-based publishing

To set up publishing:

1. For Trusted Publishing (recommended):

   • Configure trusted publishing on PyPI/TestPyPI with your GitHub repository

   • No secrets needed - uses OpenID Connect

2. For Token-based Publishing:

   • Add PYPI_API_TOKEN and TEST_PYPI_API_TOKEN secrets to your repository

   • Use the "Use twine" option in the workflow dispatch

🤝 Contributing

We welcome contributions from the community! To get started, check out our contribution guide for setup instructions, development tips, and guidelines.