AlphaVantage

You can run the AlphaVantage MCP Server to access market data, fundamentals, news, and technical indicators through a simple MCP interface. It acts as a bridge between the AlphaVantage API and MCP-compatible clients, letting you request data and analyses in a consistent, scriptable way.

How to use

You connect to the MCP server from your MCP client by configuring a server entry that runs the MCP process locally or points to a launcher script. The server exposes tools for fundamental data, market data, technical analysis, and news/sentiment that you can invoke via standard MCP commands from your client.

To start quickly, run the MCP server directly in your environment and then point your client at the running instance. The recommended method is to use the launch script or the direct runtime command shown in the usage examples. Use environment variables to provide your AlphaVantage API key securely.

How to install

Prerequisites you need before installation:

• Python 3.10 to 3.12
• uvpkg (the MCP runtime)
• AlphaVantage API key (obtainable for free)

Step-by-step installation steps:

# Clone the project (adjust <repo-url> to your actual clone URL)
git clone <repo-url>
cd alphavantage_mcp

# Install dependencies and prepare environment
uv sync

Configuration and running the server

Set your AlphaVantage API key as an environment variable to authorize requests.

# macOS/Linux
export ALPHA_VANTAGE_API_KEY=your_key_here

# Windows (Command Prompt)
set ALPHA_VANTAGE_API_KEY=your_key_here

# Windows (PowerShell)
$env:ALPHA_VANTAGE_API_KEY="your_key_here"

Or create a .env file in the project directory with your API key.

ALPHA_VANTAGE_API_KEY=your_alphavantage_api_key

Running the server can be done in several ways. The direct runtime option is the simplest for quick start.

# Direct execution
uv run alphavantage-mcp-server

If you prefer a launcher script, you can use the macOS/Linux script.

./launch-alphavantage.sh

Windows users can start with the Windows launcher script.

launch-alphavantage.bat

Configuration tips for reliability

GUI apps and certain MCP clients may not automatically inherit your shell PATH. Use absolute paths for reliability in configurations.

If you plan to run via Claude Desktop or another MCP client, provide the launcher path or the UV runtime with a clear working directory.

Examples of client configurations

Use these as starting points in your MCP client configuration to connect to the local AlphaVantage MCP Server.

{
  "mcpServers": {
    "alphavantage-data": {
      "command": "/path/to/alphavantage_mcp/launch-alphavantage.sh",
      "env": {
        "ALPHA_VANTAGE_API_KEY": "your_key"
      }
    }
  }
}

Alternatively, you can invoke the server directly via the UV runtime.

{
  "mcpServers": {
    "alphavantage-data": {
      "command": "/Users/yourname/.local/bin/uv",
      "args": ["run", "alphavantage-mcp-server"],
      "cwd": "/path/to/alphavantage_mcp",
      "env": {
        "ALPHA_VANTAGE_API_KEY": "your_key"
      }
    }
  }
}

Notes for security and best practices

Never commit API keys to version control. Use environment variables or secure secret management.

The server validates inputs to prevent injection attacks and should be kept up to date with the latest API client libraries.

Development and testing

If you are developing or testing, install development dependencies and run tests to ensure compatibility.

# Install with dev dependencies
uv sync --extra dev

# Run the server directly for testing
uv run alphavantage-mcp-server

# Run tests
uv run pytest

# Type checking
uv run mypy .

# Format code
uv run black .

Available tools

get_company_overview

Fetches company fundamentals including PE ratio, market cap, EPS, margins, and other key metrics.

get_income_statement

Retrieves annual income statement data for the last 20 periods.

get_balance_sheet

Provides annual balance sheet data for the last 20 periods.

get_cash_flow

Returns annual cash flow statements for the last 20 periods.

get_earnings

Provides quarterly or annual earnings data.

get_daily_prices

Returns daily OHLCV data with options for compact or full history.

get_intraday_prices

Fetches intraday price data at the specified timeframe.

get_market_news

Retrieves market news with sentiment analysis for specified tickers and topics.

get_technical_indicators

Calculates technical indicators such as RSI, MACD, Bollinger Bands, SMA, EMA, STOCHASTIC, ADX, and WILLIAMS_R for a given symbol and timeframe.