MCP HubMCP Hub
berlinbra

alpha-vantage-mcp

by: berlinbra

MCP Server for Alpha Advantage API

30created 17/12/2024
Visit
API
Alpha

📌Overview

Purpose: To provide real-time access to financial market data through a standardized interface using the Alpha Vantage API.

Overview: The Alpha Vantage MCP Server serves as a Model Context Protocol server that facilitates the retrieval of stock quotes and company information, as well as cryptocurrency exchange rates and historical options data.

Key Features:

  • Real-time Stock Quotes: Access the latest stock market data, including price, volume, and changes, enabling timely decision-making for investments.

  • Company Information Retrieval: Offers detailed insights about companies, such as sector, industry, and market capitalization, assisting investors in evaluating potential investments.

  • Cryptocurrency Exchange Rates: Provides real-time exchange rates with bid/ask prices for various cryptocurrencies, catering to the growing interest in digital assets.

  • Historical Options Data: Retrieves historical options chain information with advanced filtering and sorting capabilities, supporting sophisticated trading strategies.

  • Error Handling & Rate Limit Management: Implements robust error handling for various scenarios, ensuring reliability and user-friendly feedback in case of errors.

Alpha Vantage MCP Server

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.

Features

  • Real-time stock quotes with price, volume, and change data
  • Detailed company information including sector, industry, and market cap
  • Real-time cryptocurrency exchange rates with bid/ask prices
  • Daily, weekly, and monthly cryptocurrency time series data
  • Historical options chain data with advanced filtering and sorting
  • Built-in error handling and rate limit management

Installation

Using Claude Desktop

Installing via Docker

  • Clone the repository and build a local image to be utilized by your Claude desktop client
cd alpha-vantage-mcp
docker build -t mcp/alpha-vantage .
  • Change your claude_desktop_config.json to match the following, replacing REPLACE_API_KEY with your actual key:

claude_desktop_config.json path

  • On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • On Windows: %APPDATA%/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "alphavantage": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "-e",
        "ALPHA_VANTAGE_API_KEY",
        "mcp/alpha-vantage"
      ],
      "env": {
        "ALPHA_VANTAGE_API_KEY": "REPLACE_API_KEY"
      }
    }
  }
}

Installing via Smithery

To install Alpha Vantage MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @berlinbra/alpha-vantage-mcp --client claude

Development/Unpublished Servers Configuration

{
 "mcpServers": {
  "alpha-vantage-mcp": {
   "args": [
    "--directory",
    "/Users/{INSERT_USER}/YOUR/PATH/TO/alpha-vantage-mcp",
    "run",
    "alpha-vantage-mcp"
   ],
   "command": "uv",
   "env": {
    "ALPHA_VANTAGE_API_KEY": "<insert api key>"
   }
  }
 }
}

Install packages

uv install -e .

Running

After connecting Claude client with the MCP tool via json file and installing the packages, Claude should see the server's MCP tools.

Run the server in the repository directory:

uv run src/alpha_vantage_mcp/server.py

Run with inspector:

npx @modelcontextprotocol/inspector uv --directory /Users/{INSERT_USER}/YOUR/PATH/TO/alpha-vantage-mcp run src/alpha_vantage_mcp/server.py

Available Tools

The server implements eight tools:

  • get-stock-quote: Get the latest stock quote for a specific company
  • get-company-info: Get stock-related information for a specific company
  • get-crypto-exchange-rate: Get current cryptocurrency exchange rates
  • get-time-series: Get historical daily price data for a stock
  • get-historical-options: Get historical options chain data with sorting capabilities
  • get-crypto-daily: Get daily time series data for a cryptocurrency
  • get-crypto-weekly: Get weekly time series data for a cryptocurrency
  • get-crypto-monthly: Get monthly time series data for a cryptocurrency

get-stock-quote

Input Schema:

{
    "symbol": {
        "type": "string",
        "description": "Stock symbol (e.g., AAPL, MSFT)"
    }
}

Example Response:

Stock quote for AAPL:

Price: $198.50
Change: $2.50 (+1.25%)
Volume: 58942301
High: $199.62
Low: $197.20

get-company-info

Retrieves detailed company information for a given symbol.

Input Schema:

{
    "symbol": {
        "type": "string",
        "description": "Stock symbol (e.g., AAPL, MSFT)"
    }
}

Example Response:

Company information for AAPL:

Name: Apple Inc
Sector: Technology
Industry: Consumer Electronics
Market Cap: $3000000000000
Description: Apple Inc. designs, manufactures, and markets smartphones...
Exchange: NASDAQ
Currency: USD

get-crypto-exchange-rate

Retrieves real-time cryptocurrency exchange rates with additional market data.

Input Schema:

{
    "crypto_symbol": {
        "type": "string",
        "description": "Cryptocurrency symbol (e.g., BTC, ETH)"
    },
    "market": {
        "type": "string",
        "description": "Market currency (e.g., USD, EUR)",
        "default": "USD"
    }
}

Example Response:

Cryptocurrency exchange rate for BTC/USD:

From: Bitcoin (BTC)
To: United States Dollar (USD)
Exchange Rate: 43521.45000
Last Updated: 2024-12-17 19:45:00 UTC
Bid Price: 43521.00000
Ask Price: 43522.00000

get-time-series

Retrieves daily time series (OHLCV) data.

Input Schema:

{
    "symbol": {
        "type": "string",
        "description": "Stock symbol (e.g., AAPL, MSFT)"
    },
    "outputsize": {
        "type": "string",
        "description": "compact (latest 100 data points) or full (up to 20 years of data)",
        "default": "compact"
    }
}

Example Response:

Time Series Data for AAPL (Last Refreshed: 2024-12-17 16:00:00):

Date: 2024-12-16
Open: $195.09
High: $197.68
Low: $194.83
Close: $197.57
Volume: 55,751,011

get-historical-options

Retrieves historical options chain data with advanced sorting and filtering capabilities.

Input Schema:

{
    "symbol": {
        "type": "string",
        "description": "Stock symbol (e.g., AAPL, MSFT)"
    },
    "date": {
        "type": "string",
        "description": "Optional: Trading date in YYYY-MM-DD format (defaults to previous trading day, must be after 2008-01-01)",
        "pattern": "^20[0-9]{2}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$"
    },
    "limit": {
        "type": "integer",
        "description": "Optional: Number of contracts to return (default: 10, use -1 for all contracts)",
        "default": 10,
        "minimum": -1
    },
    "sort_by": {
        "type": "string",
        "description": "Optional: Field to sort by",
        "enum": ["strike", "expiration", "volume", "open_interest", "implied_volatility", "delta", "gamma", "theta", "vega", "rho", "last", "bid", "ask"],
        "default": "strike"
    },
    "sort_order": {
        "type": "string",
        "description": "Optional: Sort order",
        "enum": ["asc", "desc"],
        "default": "asc"
    }
}

Example Response:

Historical Options Data for AAPL (2024-02-20):

Contract 1:
Strike: $190.00
Expiration: 2024-03-15
Last: $8.45
Bid: $8.40
Ask: $8.50
Volume: 1245
Open Interest: 4567
Implied Volatility: 0.25
Greeks:
  Delta: 0.65
  Gamma: 0.04
  Theta: -0.15
  Vega: 0.30
  Rho: 0.25

Contract 2:
...

get-crypto-daily

Retrieves daily time series data for a cryptocurrency.

Input Schema:

{
    "symbol": {
        "type": "string",
        "description": "Cryptocurrency symbol (e.g., BTC, ETH)"
    },
    "market": {
        "type": "string",
        "description": "Market currency (e.g., USD, EUR)",
        "default": "USD"
    }
}

Example Response:

Daily cryptocurrency time series for SOL in USD:

Daily Time Series for Solana (SOL)
Market: United States Dollar (USD)
Last Refreshed: 2025-04-17 00:00:00 UTC

Date: 2025-04-17
Open: 131.31000000 USD
High: 131.67000000 USD
Low: 130.74000000 USD
Close: 131.15000000 USD
Volume: 39652.22195178
---
Date: 2025-04-16
Open: 126.10000000 USD
High: 133.91000000 USD
Low: 123.46000000 USD
Close: 131.32000000 USD
Volume: 1764240.04195810
---

get-crypto-weekly

Retrieves weekly time series data for a cryptocurrency.

Input Schema:

{
    "symbol": {
        "type": "string",
        "description": "Cryptocurrency symbol (e.g., BTC, ETH)"
    },
    "market": {
        "type": "string",
        "description": "Market currency (e.g., USD, EUR)",
        "default": "USD"
    }
}

Example Response:

Weekly cryptocurrency time series for SOL in USD:

Weekly Time Series for Solana (SOL)
Market: United States Dollar (USD)
Last Refreshed: 2025-04-17 00:00:00 UTC

Date: 2025-04-17
Open: 128.32000000 USD
High: 136.00000000 USD
Low: 123.46000000 USD
Close: 131.15000000 USD
Volume: 4823091.05667581
---
Date: 2025-04-13
Open: 105.81000000 USD
High: 134.11000000 USD
Low: 95.16000000 USD
Close: 128.32000000 USD
Volume: 18015328.38860037
---

get-crypto-monthly

Retrieves monthly time series data for a cryptocurrency.

Input Schema:

{
    "symbol": {
        "type": "string",
        "description": "Cryptocurrency symbol (e.g., BTC, ETH)"
    },
    "market": {
        "type": "string",
        "description": "Market currency (e.g., USD, EUR)",
        "default": "USD"
    }
}

Example Response:

Monthly cryptocurrency time series for SOL in USD:

Monthly Time Series for Solana (SOL)
Market: United States Dollar (USD)
Last Refreshed: 2025-04-17 00:00:00 UTC

Date: 2025-04-17
Open: 124.51000000 USD
High: 136.18000000 USD
Low: 95.16000000 USD
Close: 131.15000000 USD
Volume: 34268628.85976021
---
Date: 2025-03-31
Open: 148.09000000 USD
High: 180.00000000 USD
Low: 112.00000000 USD
Close: 124.54000000 USD
Volume: 42360395.75443056
---

Error Handling

The server includes comprehensive error handling for various scenarios:

  • Rate limit exceeded
  • Invalid API key
  • Network connectivity issues
  • Timeout handling
  • Malformed responses

Error messages are returned in a clear, human-readable format.

Prerequisites

  • Python 3.12 or higher
  • httpx
  • mcp

Contributors

  • berlinbra
  • zzulanas

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This MCP server is licensed under the MIT License. You are free to use, modify, and distribute the software under the terms of the MIT License.