Financial Data Connector MCP Server

A Model Context Protocol (MCP) service granting instantaneous access to global market intelligence via the complimentary Alpha Vantage API. This implementation offers a unified API surface for querying stock performance metrics and corporate profiles.

Capabilities

Instantaneous equity price snapshots covering valuation, transaction volume, and movement statistics
Comprehensive firm attributes: classification by sector, industry, and market cap magnitude
Real-time foreign exchange valuations for major cryptocurrencies, displaying bid/ask spreads
Historical derivatives chain data retrieval, supporting sophisticated filtering and ordering mechanisms
Integrated resilience against API access restrictions and service throttling

Deployment Instructions

Via Claude Desktop Client

Docker Containerization Method

Checkout the source repository and construct a local container image for use by your Claude desktop instance

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

Modify your configuration file (claude_desktop_config.json) to reflect these settings, substituting REPLACE_API_KEY with your validated credential:

Configuration File Location Guide

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

Smithery Integration

To automate the setup of the Alpha Vantage Connector for Claude Desktop utilizing Smithery:

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

Configuration for Development/Unreleased 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 Procedure

Once the Claude client has established a connection to the MCP service via the JSON manifest and dependencies are satisfied, the server's tools should become visible. Initiation can be performed manually from the project root:

From within the alpha-vantage-mcp directory:

uv run src/alpha_vantage_mcp/server.py

With the inspector tool active:

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

Exposed Service Methods

The connector exposes five distinct methods: - get-stock-quote: Fetch the most recent trading price for a specified security - get-company-info: Retrieve comprehensive stock-related metadata for an entity - get-crypto-exchange-rate: Determine current conversion values for digital currencies - get-time-series: Obtain historical transactional price movements for an equity - get-historical-options: Access archived options contract data, including sorting parameters

get-stock-quote

Input Specification:

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

Illustrative Output:

Security valuation for AAPL:

Price: $198.50
Movement: $2.50 (+1.25%)
Volume: 58942301
Peak Price (Day): $199.62
Trough Price (Day): $197.20

get-company-info

Fetches comprehensive organizational metadata associated with a security ticker.

Input Specification:

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

Illustrative Output:

Corporate profile for AAPL:

Entity Name: Apple Inc
Classification Sector: Technology
Sub-Sector Industry: Consumer Electronics
Total Valuation: $3000000000000
Business Summary: Apple Inc. designs, manufactures, and markets smartphones...
Trading Venue: NASDAQ
Denomination Currency: USD

get-crypto-exchange-rate

Retrieves the present conversion ratios for digital currencies, along with supplementary market indicators.

Input Specification:

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

Illustrative Output:

Digital asset exchange rate for BTC/USD:

Base Asset: Bitcoin (BTC)
Quote Asset: United States Dollar (USD)
Rate of Exchange: 43521.45000
Last Data Timestamp: 2024-12-17 19:45:00 UTC
Quoted Purchase Price: 43521.00000
Quoted Sale Price: 43522.00000

get-time-series

Obtains historical daily OHLCV (Open, High, Low, Close, Volume) datasets.

Input Specification:

{
    "symbol": {
        "type": "string",
        "description": "Security ticker identifier (e.g., AAPL, MSFT)"
    },
    "outputsize": {
        "type": "string",
        "description": "compact (last 100 records) or full (up to 20 years of history)",
        "default": "compact"
    }
}

Illustrative Output:

Historical Price Progression for AAPL (Data Refreshed As Of: 2024-12-17 16:00:00):

Trading Date: 2024-12-16
Opening Price: $195.09
Maximum Price: $197.68
Minimum Price: $194.83
Closing Price: $197.57
Transaction Volume: 55,751,011

get-historical-options

Retrieves archived options contract records, enabling advanced sorting and data extraction.

Input Specification:

{
    "symbol": {
        "type": "string",
        "description": "Security ticker 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: Maximum number of contracts to return (default: 10, use -1 for all contracts)",
        "default": 10,
        "minimum": -1
    },
    "sort_by": {
        "type": "string",
        "description": "Optional: Attribute name for ordering",
        "enum": ["strike", "expiration", "volume", "open_interest", "implied_volatility", "delta", "gamma", "theta", "vega", "rho", "last", "bid", "ask"],
        "default": "strike"
    },
    "sort_order": {
        "type": "string",
        "description": "Optional: Order direction",
        "enum": ["asc", "desc"],
        "default": "asc"
    }
}

Illustrative Output:

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

Contract Identifier 1:
Execution Price: $190.00
Expiry Date: 2024-03-15
Last Trade Price: $8.45
Best Bid: $8.40
Best Ask: $8.50
Transaction Count: 1245
Outstanding Contracts: 4567
Implied Volatility Factor: 0.25
Greeks Metrics:
  Delta Factor: 0.65
  Gamma Factor: 0.04
  Theta Factor: -0.15
  Vega Factor: 0.30
  Rho Factor: 0.25

Contract Identifier 2:
...

Error Resiliency

The service incorporates robust fault tolerance for various failure modes:

API call quota exhaustion
Invalid credential submission
External network pathway interruptions
Operation timeouts
Non-compliant data responses

The system communicates failures through explicit, readily understandable messages.

Dependencies

Python environment version 3.12 or newer
httpx library
mcp package

Project Collaborators

Contribution Guidelines

We welcome external feature additions or fixes! Please submit a Pull Request for consideration.

Licensing

This MCP service operates under the MIT License terms. You are permitted to deploy, alter, and disseminate this software, contingent upon adherence to the stipulations outlined in the MIT License agreement found in the project's primary LICENSE file.

WIKIPEDIA: Cloud computing is "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand," according to ISO. It is commonly referred to as "the cloud".

== Foundational Attributes == In 2011, the National Institute of Standards and Technology (NIST) cataloged five "essential attributes" defining cloud systems. The precise definitions from NIST are enumerated below:

On-demand self-service: "A consumer can unilaterally provision computing capabilities, such as server time and network storage, as needed automatically without requiring human interaction with each service provider." Broad network access: "Capabilities are available over the network and accessed through standard mechanisms that promote use by heterogeneous thin or thick client platforms (e.g., mobile phones, tablets, laptops, and workstations)." Resource pooling: " The provider's computing resources are pooled to serve multiple consumers using a multi-tenant model, with different physical and virtual resources dynamically assigned and reassigned according to consumer demand." Rapid elasticity: "Capabilities can be elastically provisioned and released, in some cases automatically, to scale rapidly outward and inward commensurate with demand. To the consumer, the capabilities available for provisioning often appear unlimited and can be appropriated in any quantity at any time." Measured service: "Cloud systems automatically control and optimize resource use by leveraging a metering capability at some level of abstraction appropriate to the type of service (e.g., storage, processing, bandwidth, and active user accounts). Resource usage can be monitored, controlled, and reported, providing transparency for both the provider and consumer of the utilized service. By 2023, the International Organization for Standardization (ISO) had expanded and refined the list.

== Historical Progression ==

The conceptual lineage of cloud computation traces back to the 1960s, marked by the initial popularization of time-sharing via remote job entry (RJE). The 'data center' operational model, where users delegated tasks to human operators for mainframe execution, dominated this era. This period fostered innovation in making high-capacity computation accessible to a wider user base through time-sharing, thereby maximizing infrastructure, platform, and application utilization, leading to greater end-user productivity. The term 'cloud' for virtualization concepts emerged in 1994, employed by General Magic to describe the conceptual space mobile agents in their Telescript environment could navigate. This nomenclature is attributed to David Hoffman, an associate at General Magic, based on its established usage in telecommunications networking. The phrase 'cloud computing' gained broader recognition in 1996 when Compaq Computer Corporation drafted a strategy for subsequent internet and computational advancements. The firm's objective was to superch