This project provides a Model Context Protocol (MCP) server that wraps the @missionsquad/avantage
library, exposing Alpha Vantage API functionalities as tools for Language Learning Models (LLMs).
This server allows LLMs to interact with the Alpha Vantage API to retrieve financial data, including:
- Core Stock Data (Time Series, Quotes, Search)
- Fundamental Data (Company Overview, Financials, Calendars)
- Forex (FX) Data
- Cryptocurrency Data
- Commodities Data
- Economic Indicators
- Technical Indicators
- Alpha Intelligence (News, Sentiments, etc.)
- Options Data (Premium)
It leverages the @missionsquad/avantage
TypeScript library and follows the architecture of the generic MCP server template, including multi-user API key handling and resource management for AVantage
client instances.
Key Features:
-
Comprehensive Coverage: Implements MCP tools for nearly all functions available in the
@missionsquad/avantage
library. -
Multi-User Support: Handles Alpha Vantage API keys securely via
extraArgs
(preferred) or fallback to environment variables. -
Resource Management: Efficiently manages
AVantage
client instances using theResourceManager
. -
Strongly Typed: Built with TypeScript, leveraging types from
@missionsquad/avantage
and Zod schemas for tool parameters. -
Standard MCP Interface: Uses
@missionsquad/fastmcp
for MCP communication.
- Node.js v20 or later
- npm or yarn
- An Alpha Vantage API Key (Get one here)
-
Clone or Copy: Clone this repository or copy the files.
git clone <repository-url> mcp-avantage-server cd mcp-avantage-server
-
Install Dependencies:
npm install # or yarn install
-
Configure Environment:
- Copy
.env.example
to.env
. - Edit
.env
and setAPI_KEY
to your Alpha Vantage API key. - Optionally set
AV_PREMIUM=true
if you have a premium subscription. - Adjust
LOG_LEVEL
orRESOURCE_CLEANUP_INTERVAL
if needed.
- Copy
-
Build the Project:
npm run build # or yarn build
-
Start the Server:
The server will listen for MCP requests on stdio.
npm start # or yarn start
The server uses the standard multi-user token handling pattern:
-
extraArgs.apiKey
(Recommended): Pass the user-specific Alpha Vantage API key in theapiKey
field of theextraArgs
object during the MCPcall_tool
request. This key is not part of the tool's schema. -
.env
Fallback: IfextraArgs.apiKey
is not provided, the server uses theAPI_KEY
value from the.env
file.
This server exposes numerous tools corresponding to the methods in the @missionsquad/avantage
library. Tools are generally named module_method
(e.g., coreStock_intraday
, fundamentalData_companyOverview
).
Refer to the Alpha Vantage documentation and the @missionsquad/avantage
library's types (src/types/*
within the library) for details on parameters and return structures.
Example Tool Call (Conceptual MCP Request):
{
"type": "call_tool",
"requestId": "req-123",
"tool": {
"name": "coreStock_quote",
"arguments": {
"symbol": "IBM"
}
},
"context": {
"extraArgs": {
"apiKey": "USER_SPECIFIC_AV_KEY" // Optional: User's key
}
}
}
Tool Categories (Modules):
alphaIntelligence_*
commodities_*
coreStock_*
crypto_*
economicIndicators_*
forex_*
fundamentalData_*
-
optionsData_*
(Premium) technicalIndicators_*
Use the MCP list_tools
command to get the full list of available tools, their descriptions, and parameter schemas.
Configure via .env
file:
Variable | Description | Default |
---|---|---|
API_KEY |
Fallback Alpha Vantage API key if not in extraArgs
|
null |
LOG_LEVEL |
Logging level (error , warn , info , debug ) |
info |
RESOURCE_CLEANUP_INTERVAL |
Interval (ms) to clean up inactive AVantage client instances |
1800000 (30m) |
AV_PREMIUM |
Set to true to enable premium endpoint access in avantage
|
false |
Follows the generic MCP server template structure. Key files:
-
src/index.ts
: Main server entry point, tool definitions. -
src/config.ts
: Configuration loading. -
src/logger.ts
: Logging utility. -
src/resource-manager.ts
: ManagesAVantage
instances. -
src/schemas.ts
: Zod schemas for tool parameters. -
.nexus/
: Nexus documentation.
.nexus/features/avantage_integration/feature.md
.nexus/architecture/server_structure.md
.nexus/guides/using_avantage_tools.md
.nexus/decisions/decision_log.md
MIT (Assuming the template license is MIT. Verify.)