Alpha Vantage MCP Server

What is Alpha Vantage MCP Server about?

Enables clients to retrieve real‑time and historical stock market data from the Alpha Vantage API through a Model Context Protocol (MCP) server. The server can run locally in stdio mode for desktop tools or as a streamable HTTP service, optionally protected by OAuth 2.1.

How to use Alpha Vantage MCP Server?

1. Obtain an Alpha Vantage API key and set it in the environment variable ALPHAVANTAGE_API_KEY.
2. Clone the repository:

   git clone https://github.com/calvernaz/alphavantage.git
   cd alphavantage
   

3. Run in stdio mode (default):

   alphavantage
   # or explicitly
   alphavantage --server stdio
   

4. Run as a streamable HTTP server:

   alphavantage --server http --port 8080
   

5. Enable OAuth 2.1 (requires HTTP mode):

   export OAUTH_AUTHORIZATION_SERVER_URL="https://your-auth-server.com/realms/your-realm"
   export OAUTH_RESOURCE_SERVER_URI="https://your-mcp-server.com"
   # optional JWT or introspection settings …
   alphavantage --server http --port 8080 --oauth
   

6. Deploy to AWS Lambda using the provided deploy/aws-stateless-mcp-lambda script for a serverless, auto‑scaling setup.

Key features of Alpha Vantage MCP Server

• Two operation modes: stdio for local tools and HTTP streaming for networked clients.
• OAuth 2.1 protection with JWT validation or token introspection, metadata endpoint, and proper security headers.
• Stateless MCP pattern suitable for AWS Lambda and other serverless platforms.
• Easy configuration via environment variables (API key, OAuth parameters, port, etc.).
• Demo video and extensive documentation for quick onboarding.

Use cases of Alpha Vantage MCP Server

• Integrating live stock quotes into AI assistants or chatbots.
• Supplying market data to financial analytics dashboards.
• Building serverless micro‑services that query Alpha Vantage on demand.
• Securing data access in enterprise environments with OAuth.
• Enabling Claude Desktop or similar tools to fetch financial information without exposing raw API keys.

FAQ from Alpha Vantage MCP Server

Q: Do I need a paid Alpha Vantage plan? A: No. A free API key is sufficient for typical usage; higher rate limits require a paid plan.

Q: Can I run the server behind a reverse proxy? A: Yes. When using HTTP mode, any standard reverse proxy (nginx, CloudFront, API Gateway) works.

Q: Which OAuth token validation method should I choose? A: Use jwt if you control the public key; otherwise introspection works with providers like Keycloak.

Q: How does the server handle rate limits? A: The server forwards requests directly to Alpha Vantage; you must respect the provider's rate‑limit policy.

Q: Is the server compatible with Windows? A: Yes, the Python/uv based CLI runs on Windows, macOS, and Linux.

✅ Official Alpha Vantage MCP Server

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

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

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

Clone the project

git clone https://github.com/calvernaz/alphavantage.git

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.

alphavantage
# or explicitly:
alphavantage --server stdio

Streamable HTTP Server

This mode provides real-time updates via HTTP streaming.

alphavantage --server http --port 8080

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.

alphavantage --server http --port 8080 --oauth

OAuth Configuration

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

Required Environment Variables:

export OAUTH_AUTHORIZATION_SERVER_URL="https://your-auth-server.com/realms/your-realm"
export OAUTH_RESOURCE_SERVER_URI="https://your-mcp-server.com"

Optional Environment Variables:

# Token validation method (default: jwt)
export OAUTH_TOKEN_VALIDATION_METHOD="jwt"  # or "introspection"

# For JWT validation
export OAUTH_JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
export OAUTH_JWT_ALGORITHM="RS256"  # default

# For token introspection validation
export OAUTH_INTROSPECTION_ENDPOINT="https://your-auth-server.com/realms/your-realm/protocol/openid-connect/token/introspect"
export OAUTH_INTROSPECTION_CLIENT_ID="your-client-id"
export OAUTH_INTROSPECTION_CLIENT_SECRET="your-client-secret"

# Optional: Required scopes (space-separated)
export OAUTH_REQUIRED_SCOPES="mcp:access mcp:read"

# Optional: Enable session binding for additional security (default: true)
export OAUTH_SESSION_BINDING_ENABLED="true"

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:

# Keycloak OAuth configuration
export OAUTH_AUTHORIZATION_SERVER_URL="https://keycloak.example.com/realms/mcp-realm"
export OAUTH_RESOURCE_SERVER_URI="https://mcp.example.com"
export OAUTH_TOKEN_VALIDATION_METHOD="introspection"
export OAUTH_INTROSPECTION_ENDPOINT="https://keycloak.example.com/realms/mcp-realm/protocol/openid-connect/token/introspect"
export OAUTH_INTROSPECTION_CLIENT_ID="mcp-server"
export OAUTH_INTROSPECTION_CLIENT_SECRET="your-keycloak-client-secret"
export OAUTH_REQUIRED_SCOPES="mcp:access"

# Start server with OAuth
alphavantage --server http --port 8080 --oauth

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)

🚀 AWS Serverless Deployment

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

Quick AWS Deployment

cd deploy/aws-stateless-mcp-lambda
export ALPHAVANTAGE_API_KEY=your_api_key_here
./deploy.sh

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

Add this to your claude_desktop_config.json:

NOTE Make sure you replace the <DIRECTORY-OF-CLONED-PROJECT> with the directory of the cloned project.

{
  "mcpServers": {
    "alphavantage": {
      "command": "uv",
      "args": [
        "--directory",
        "<DIRECTORY-OF-CLONED-PROJECT>/alphavantage",
        "run",
        "alphavantage"
      ],
      "env": {
        "ALPHAVANTAGE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Running the Server in Streamable HTTP Mode

{
  "mcpServers": {
    "alphavantage": {
      "command": "uv",
      "args": [
        "--directory",
        "<DIRECTORY-OF-CLONED-PROJECT>/alphavantage",
        "run",
        "alphavantage",
        "--server",
        "http",
        "--port",
        "8080"
      ],
      "env": {
        "ALPHAVANTAGE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

📺 Demo Video

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

🤝 Contributing

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