Financial Data Access Hub (AlphaVantage Integration)

This server operates as an MCP interface layer, facilitating synchronous access to the comprehensive data catalog provided by the complimentary Alpha Vantage API. It formalizes an interaction schema for obtaining stock price snapshots and organizational profiles.

Core Capabilities

Immediate retrieval of equity transaction summaries: pricing, traded volume, and performance metrics.
In-depth corporate descriptor retrieval, encompassing sector classification, industry grouping, and total market capitalization.
Up-to-the-second parity assessments for specified digital currency pairs.
Historical time-series data access for digital currencies across daily, weekly, and monthly granularities.
Access to historical option contract data, featuring advanced query refinement parameters.
Embedded mechanisms for error reporting and management of external service request quotas.

Deployment Procedures

Utilizing the Claude Desktop Environment

Docker Image Setup

Clone the source repository and compile a local container artifact for use by your local Claude client instance.

cd alpha-vantage-mcp
docker build -t mcp/alpha-vantage .

Modify the configuration file claude_desktop_config.json as shown below, substituting the placeholder REPLACE_API_KEY with your credential:

claude_desktop_config.json Location Details

macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json

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"
      }
    }
  }
}

Installation via Smithery Registry

To streamline the setup of the Alpha Vantage MCP Server for Claude Desktop deployment using Smithery:

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

Configuration for Experimental/Local Servers

{
 "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>"
   }
  }
 }
}

Dependency Installation

uv install -e .

Execution

Once the Claude client is linked to the MCP service via the configuration file and dependencies are resolved, the server's tools become accessible. Execute the server manually from the project root directory using:

In alpha-vantage-mcp repo:

uv run src/alpha_vantage_mcp/server.py

To enable inspection capabilities:

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

Available Functions

The service exposes eight distinct callable functions: - get-stock-quote: Fetches the most current pricing datum for a specified equity instrument. - get-company-info: Obtains comprehensive descriptive metadata associated with a stock ticker. - get-crypto-exchange-rate: Queries the prevailing exchange ratio for cryptocurrencies. - get-time-series: Retrieves historical daily trade records (OHLCV) for equities. - get-historical-options: Accesses records of past option contracts, supporting advanced result set manipulation. - get-crypto-daily: Pulls daily interval historical data for a given digital asset. - get-crypto-weekly: Pulls weekly interval historical data for a given digital asset. - get-crypto-monthly: Pulls monthly interval historical data for a given digital asset.

get-stock-quote

Input Parameters:

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

Sample Output:

Stock quote for AAPL:

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

get-company-info

Retrieves extensive descriptive metadata pertaining to a specified stock symbol.

Input Parameters:

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

Sample Output:

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

Fetches instantaneous exchange rate data for digital currencies, accompanied by supplementary market metrics.

Input Parameters:

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

Sample Output:

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 historical records aggregated on a daily basis (Open, High, Low, Close, Volume).

Input Parameters:

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

Sample Output:

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

Fetches historical data for options chains, supporting mechanisms for result ordering and result count limitation.

Input Parameters:

{
    "symbol": {
        "type": "string",
        "description": "Stock identifier (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 direction",
        "enum": ["asc", "desc"],
        "default": "asc"
    }
}

Sample Output:

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 the closing metrics for digital assets on a daily cadence.

Input Parameters:

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

Sample Output:

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 the closing metrics for digital assets aggregated on a weekly basis.

Input Parameters:

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

Sample Output:

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 the closing metrics for digital assets aggregated on a monthly basis.

Input Parameters:

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

Sample Output:

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
---

Exception Management

The service incorporates thorough protocols for addressing operational failures, including:

Exceeding defined service request frequency thresholds.
Authentication failure due to an invalid API access token.
Disruptions in underlying network connectivity.
Timeouts during external data fetching operations.
Receipt of improperly structured responses from the provider.

All fault notifications are conveyed in a readily comprehensible narrative format.

System Requirements

Execution Environment: Python version 3.12 or later
Required Libraries: httpx, mcp

Contributors List

Path to Contribution

We welcome external input! Please submit a standard Pull Request for review.

Licensing Information

This MCP gateway is distributed under the permissive MIT License. This grants users the liberty to employ, modify, and disseminate the software, subject only to the explicit terms documented in the MIT License file within the project's source directory.

WIKIPEDIA: XMLHttpRequest (XHR) is an API in the form of a JavaScript object whose methods transmit HTTP requests from a web browser to a web server. The methods allow a browser-based application to send requests to the server after page loading is complete, and receive information back. XMLHttpRequest is a component of Ajax programming. Prior to Ajax, hyperlinks and form submissions were the primary mechanisms for interacting with the server, often replacing the current page with another one.

== History == The concept behind XMLHttpRequest was conceived in 2000 by the developers of Microsoft Outlook. The concept was then implemented within the Internet Explorer 5 browser (1999). However, the original syntax did not use the XMLHttpRequest identifier. Instead, the developers used the identifiers ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (2006), all browsers support the XMLHttpRequest identifier. The XMLHttpRequest identifier is now the de facto standard in all the major browsers, including Mozilla's Gecko layout engine (2002), Safari 1.2 (2004) and Opera 8.0 (2005).

=== Standards === The World Wide Web Consortium (W3C) published a Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C published the Working Draft Level 2 specification. Level 2 added methods to monitor event progress, allow cross-site requests, and handle byte streams. At the end of 2011, the Level 2 specification was absorbed into the original specification. At the end of 2012, the WHATWG took over development and maintains a living document using Web IDL.

== Usage == Generally, sending a request with XMLHttpRequest has several programming steps.

Create an XMLHttpRequest object by calling a constructor: Call the "open" method to specify the request type, identify the relevant resource, and select synchronous or asynchronous operation: For an asynchronous request, set a listener that will be notified when the request's state changes: Initiate the request by calling the "send" method: Respond to state changes in the event listener. If the server sends response data, by default it is captured in the "responseText" property. When the object stops processing the response, it changes to state 4, the "done" state. Aside from these general steps, XMLHttpRequest has many options to control how the request is sent and how the response is processed. Custom header fields can be added to the request to indicate how the server should fulfill it, and data can be uploaded to the server by providing it in the "send" call. The response can be parsed from the JSON format into a readily usable JavaScript object, or processed gradually as it arrives rather than waiting for the entire text. The request can be aborted prematurely or set to fail if not completed in a specified amount of time.

== Cross-domain requests ==

In the early development of the World Wide Web, it was found possible to brea