✅ 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
- Sign up for a Free Alphavantage API key
- 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:
# Run directly without installation
uvx alphavantage-mcp
# Or with specific arguments
uvx alphavantage-mcp --server http --port 8080
Option 2: Using pip
pip install alphavantage-mcp
alphavantage-mcp
Option 3: From source
git clone https://github.com/calvernaz/alphavantage.git
cd alphavantage
uv run alphavantage
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:
- Discover the authorization server via
GET /.well-known/oauth-protected-resource - Register with the authorization server (if using Dynamic Client Registration)
- Obtain access tokens from the authorization server
- Include tokens in requests:
Authorization: Bearer <access-token> - Handle 401/403 responses and refresh tokens as needed
Options:
--server: Choose betweenstdio(default) orhttpserver 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:
# Enable telemetry (default: true)
export MCP_TELEMETRY_ENABLED=true
# Server identification (optional)
export MCP_SERVER_NAME=alphavantage
export MCP_SERVER_VERSION=1.0.0
# Metrics server port (default: 9464)
export MCP_METRICS_PORT=9464
Metrics Endpoint
When telemetry is enabled, Prometheus metrics are available at:
http://localhost:9464/metrics
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 histogrammcp_tool_request_bytes- Request payload size histogrammcp_tool_response_bytes- Response payload size histogrammcp_tool_active_concurrency- Active concurrent tool calls gaugemcp_tool_errors_total- Total errors by type (timeout, bad_input, connection, unknown)
Example Usage with Telemetry
# Start server with telemetry enabled
export MCP_TELEMETRY_ENABLED=true
export MCP_SERVER_NAME=alphavantage-prod
export ALPHAVANTAGE_API_KEY=your_api_key
alphavantage --server http --port 8080
# View metrics
curl http://localhost:9464/metrics
🚀 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
Option 1: Using uvx (Recommended)
Add this to your claude_desktop_config.json:
{
"mcpServers": {
"alphavantage": {
"command": "uvx",
"args": ["alphavantage-mcp"],
"env": {
"ALPHAVANTAGE_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}
Option 2: From source
If you cloned the repository, use this configuration:
{
"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
Using uvx:
{
"mcpServers": {
"alphavantage": {
"command": "uvx",
"args": ["alphavantage-mcp", "--server", "http", "--port", "8080"],
"env": {
"ALPHAVANTAGE_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}
From source:
{
"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:
🔧 Development & Publishing
Publishing to PyPI
This project includes scripts for publishing to PyPI and TestPyPI:
# Publish to TestPyPI (for testing)
python scripts/publish.py --test
# Publish to PyPI (production)
python scripts/publish.py
# Use uv publish instead of twine
python scripts/publish.py --test --use-uv
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:
-
For Trusted Publishing (recommended):
- Configure trusted publishing on PyPI/TestPyPI with your GitHub repository
- No secrets needed - uses OpenID Connect
-
For Token-based Publishing:
- Add
PYPI_API_TOKENandTEST_PYPI_API_TOKENsecrets to your repository - Use the "Use twine" option in the workflow dispatch
- Add
🤝 Contributing
We welcome contributions from the community! To get started, check out our contribution guide for setup instructions, development tips, and guidelines.