Financial Data Gateway MCP Server

A Model Context Protocol (MCP) endpoint offering immediate access to global financial market intelligence using the complimentary Alpha Vantage API. This service establishes a unified conduit for querying stock performance indicators and foundational enterprise data.

Capabilities

• Current stock valuations featuring pricing, transaction volume, and performance delta
• In-depth enterprise particulars: sector, specialized industry, and equity valuation metrics
• Live conversion rates for digital currencies, including bid and ask spreads
• Historical derivatives chain records with sophisticated retrieval parameters
• Integrated exception management and request throttling control

Deployment Instructions

Using Claude Desktop Environment

Deployment via Docker Containerization

• Clone the source repository and construct a local container image for consumption by your Claude desktop application

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

• Modify your configuration file named claude_desktop_config.json to reflect the subsequent settings, substituting REPLACE_API_KEY with your valid credential:

Path to claude_desktop_config.json:

• On macOS systems: ~/Library/Application\ Support/Claude/claude_desktop_config.json
• On Windows systems: %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" } } } }

Deployment via Smithery Utility

To integrate the Alpha Vantage MCP Service for Claude Desktop automatically using Smithery:

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

Configuration for Development/Pre-release Services

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

Package Installation

uv install -e .

Execution Guide

Once the Claude client is linked to the MCP utility via the JSON file and dependencies are resolved, Claude should recognize the service endpoints:

You can manually activate the service using: In the alpha-vantage-mcp project directory:

uv run src/alpha_vantage_mcp/server.py

With debugging interface active:

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

Accessible Endpoints

The service exposes five distinct programmatic endpoints: - get-stock-quote: Fetches the most recent trading data for a specified equity symbol - get-company-info: Retrieves foundational descriptive metadata for a security - get-crypto-exchange-rate: Obtains current parity rates between specified digital assets - get-time-series: Queries historical daily market activity data (OHLCV) - get-historical-options: Accesses historic options contract records with sorting and filtering capabilities

get-stock-quote

Input Structure:

{ "symbol": { "type": "string", "description": "Equity ticker 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

Fetches extensive corporate metadata associated with a provided ticker.

Input Structure:

{ "symbol": { "type": "string", "description": "Equity ticker 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

Retrieves up-to-the-minute conversion factors for cryptocurrencies, including supplementary market metrics.

Input Structure:

{ "crypto_symbol": { "type": "string", "description": "Cryptocurrency identifier (e.g., BTC, ETH)" }, "market": { "type": "string", "description": "Base fiat currency (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

Queries historical time-sequenced OHLCV records.

Input Structure:

{ "symbol": { "type": "string", "description": "Equity ticker identifier (e.g., AAPL, MSFT)" }, "outputsize": { "type": "string", "description": "compact (last 100 data points) or full (up to 20 years of history)", "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

Retrieves historical derivatives chain data, allowing for granular sorting and data constraints.

Input Structure:

{ "symbol": { "type": "string", "description": "Equity ticker identifier (e.g., AAPL, MSFT)" }, "date": { "type": "string", "description": "Optional: Trading date formatted as YYYY-MM-DD (defaults to preceding trading day, must be post-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: Maximum number of contracts to return (default: 10, use -1 for all contracts)", "default": 10, "minimum": -1 }, "sort_by": { "type": "string", "description": "Optional: Field name used for ordering results", "enum": ["strike", "expiration", "volume", "open_interest", "implied_volatility", "delta", "gamma", "theta", "vega", "rho", "last", "bid", "ask"], "default": "strike" }, "sort_order": { "type": "string", "description": "Optional: Direction of ordering", "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: ...

Exception Management

The service incorporates extensive failure detection for various failure modes:

• Exceeded request quota
• Invalid operational key
• Failures in network communication
• Request timeouts
• Response data corruption

All reported exceptions are conveyed in an easily interpretable, human-friendly textual format.

Dependencies

• Python version 3.12 or newer
• The 'httpx' library
• The 'mcp' framework package

Contributors

• berlinbra
• zzulanas

Collaboration Guidelines

We welcome outside contributions! Feel encouraged to submit a Merge Request.

Licensing

This MCP service operates under the terms of the MIT License. This grants permission to utilize, alter, and disseminate the software, contingent upon adherence to the MIT License stipulations. Detailed terms are available in the repository's LICENSE file.

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