MissionSquad/mcp-avantage
If you are the rightful owner of mcp-avantage and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
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).
MCP Server for Alpha Vantage API (@missionsquad/avantage)
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).
Overview
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/avantagelibrary. - Multi-User Support: Handles Alpha Vantage API keys securely via
extraArgs(preferred) or fallback to environment variables. - Resource Management: Efficiently manages
AVantageclient instances using theResourceManager. - Strongly Typed: Built with TypeScript, leveraging types from
@missionsquad/avantageand Zod schemas for tool parameters. - Standard MCP Interface: Uses
@missionsquad/fastmcpfor MCP communication.
Getting Started
Prerequisites
- Node.js v20 or later
- npm or yarn
- An Alpha Vantage API Key (Get one here)
Setup
- 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.exampleto.env. - Edit
.envand setAPI_KEYto your Alpha Vantage API key. - Optionally set
AV_PREMIUM=trueif you have a premium subscription. - Adjust
LOG_LEVELorRESOURCE_CLEANUP_INTERVALif 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
Authentication
The server uses the standard multi-user token handling pattern:
extraArgs.apiKey(Recommended): Pass the user-specific Alpha Vantage API key in theapiKeyfield of theextraArgsobject during the MCPcall_toolrequest. This key is not part of the tool's schema..envFallback: IfextraArgs.apiKeyis not provided, the server uses theAPI_KEYvalue from the.envfile.
Available Tools
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.
Configuration
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 |
Project Structure
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: ManagesAVantageinstances.src/schemas.ts: Zod schemas for tool parameters..nexus/: Nexus documentation.
Nexus Documentation
License
MIT (Assuming the template license is MIT. Verify.)
