Financial APIs MCP Server

MCP Server connecting Claude/AI agents to real-time financial data. Stock quotes, crypto prices, historical data, forex rates, and AI-powered market analysis.

Features

• Real-time Stock Quotes - Get current price, change, volume, and key metrics
• Historical Stock Data - OHLCV data with multiple intervals (1min to monthly)
• Crypto Quotes - Real-time prices for 50+ cryptocurrencies via CoinGecko
• Crypto History - Historical price, market cap, and volume data
• Market Summary - Major indices (S&P 500, NASDAQ, DOW) and top crypto
• Forex Rates - Currency exchange rates for 150+ currencies
• AI Analysis - GPT-4 powered market analysis (technical, fundamental, sentiment)

Data Sources

Source	Data Types	Rate Limits
Alpha Vantage	Stocks, Forex	25/day (free), 75/min (premium)
CoinGecko	Crypto	10-30/min (free)

Tools

finance.stock_quote

Get real-time stock price and key metrics.

{
  "tool": "finance.stock_quote",
  "symbol": "AAPL",
  "alphaVantageApiKey": "your-api-key"
}

finance.stock_history

Get historical OHLCV data.

{
  "tool": "finance.stock_history",
  "symbol": "AAPL",
  "interval": "daily",
  "outputSize": "compact",
  "alphaVantageApiKey": "your-api-key"
}

Intervals: 1min, 5min, 15min, 30min, 60min, daily, weekly, monthly

finance.crypto_quote

Get real-time crypto price from CoinGecko. No API key required.

{
  "tool": "finance.crypto_quote",
  "symbol": "BTC"
}

Supported symbols: BTC, ETH, SOL, XRP, DOGE, ADA, AVAX, DOT, MATIC, LINK, UNI, ATOM, LTC, and 40+ more.

finance.crypto_history

Get historical crypto data. No API key required.

{
  "tool": "finance.crypto_history",
  "symbol": "ETH",
  "days": 30
}

finance.market_summary

Get major market indices and top crypto. Works without an API key (crypto only). Add Alpha Vantage key to include stock indices.

{
  "tool": "finance.market_summary",
  "alphaVantageApiKey": "your-api-key (optional)"
}

finance.currency_rate

Get forex exchange rates.

{
  "tool": "finance.currency_rate",
  "fromCurrency": "USD",
  "toCurrency": "EUR",
  "alphaVantageApiKey": "your-api-key"
}

finance.ai_analyze

AI-powered market analysis using GPT-4.

{
  "tool": "finance.ai_analyze",
  "symbol": "AAPL",
  "assetType": "stock",
  "analysisType": "comprehensive",
  "alphaVantageApiKey": "your-api-key",
  "openaiApiKey": "your-openai-key"
}

Analysis types:

• summary - Quick overview
• technical - Chart patterns and indicators
• fundamental - Valuation and financials
• sentiment - Market sentiment analysis
• comprehensive - Full analysis

API Keys

Alpha Vantage (Required for stocks/forex)

1. Get a free API key at https://www.alphavantage.co/support/#api-key
2. Free tier: 25 API calls/day
3. Premium plans available for higher limits

OpenAI (Required for AI analysis)

1. Get your API key from https://platform.openai.com/api-keys
2. Uses GPT-4o by default (configurable)

CoinGecko (No key required)

• Crypto data works without an API key
• Free tier: 10-30 calls/minute

Response Format

All tools return a consistent response structure:

{
  "status": "ok",
  "errors": [],
  "warnings": [],
  "artifacts": [],
  ...data
}

Running & Output

On Apify, each run executes one tool. Set tool plus its parameters in the run input; the actor runs that single tool call and writes the result to the run's default dataset. Two record shapes are pushed:

• A server_info record (version, tool list, data sources) at the start of every run.
• A tool_result record containing tool, status, and the tool's response fields (quote, history, rate, analysis, indices, etc.). On failure an error record is pushed instead.

If a tool produces an artifact (currently only finance.ai_analyze, which saves an analysis JSON), the file is written to the run's default key-value store under its filename.

Local HTTP server

For local development / self-hosting, npm run start:local starts a plain HTTP server (server/index.js, default port 3000) exposing REST endpoints — this is not an MCP-protocol transport:

Method	Path	Description
GET	/health	Server status and tool list
GET	/tools	List available tools
POST	/tool/{name}	Execute a tool (JSON body = params)
GET	/artifact/{id}	Download an in-memory artifact

curl -X POST http://localhost:3000/tool/finance.crypto_quote \
  -H "Content-Type: application/json" \
  -d '{"symbol": "BTC"}'

Error Codes

Code	Description
INVALID_SYMBOL	Stock/crypto symbol not found
RATE_LIMITED	API rate limit exceeded
NO_API_KEY	Required API key not provided
INVALID_INPUT	Missing or malformed parameters
INVALID_INTERVAL	Invalid time interval for historical data
INVALID_DATE_RANGE	Invalid date range (crypto days must be 1-365)
AI_ERROR	OpenAI API error
API_ERROR	External API error
MARKET_CLOSED	Market not currently open
INTERNAL_ERROR	Unexpected server error

Local Development

# Install dependencies
npm install

# Run tests (mocked)
npm test

# Run tests (live - requires API keys)
ALPHA_VANTAGE_API_KEY=xxx npm run test:live

Deployment to Apify

# Using Apify CLI
apify login
apify push

Pricing

This actor is designed for PPE (Pay Per Event) pricing on Apify:

• Each tool call = 1 event
• Minimal compute usage
• No browser/Playwright required (unlike PDF server)

Agent Integration

The tools use MCP-style names (finance.*) and return a uniform JSON envelope, which makes them straightforward to wire into an AI agent or automation. On Apify the actor is invoked per run via the input schema (one tool per run, result in the dataset); the local HTTP server exposes the same tools over the REST endpoints listed above. Note: this build does not ship a native MCP-protocol / JSON-RPC transport or an Apify Standby endpoint — integrate it through the Apify run input or the local REST endpoints.

Limitations

• Depends on external APIs. All data comes from Alpha Vantage (stocks, forex), CoinGecko (crypto), and OpenAI (finance.ai_analyze). If any of these is unreachable, rate-limited, or changes its response format, the affected tool returns a structured error (API_ERROR, RATE_LIMITED, AI_ERROR) rather than data.
• Rate limits are strict on free tiers. Alpha Vantage free tier is ~25 calls/day; CoinGecko free tier is ~10-30 calls/minute. Heavy use requires paid API plans.
• API keys required. Stock, forex, and stock AI-analysis tools require your own Alpha Vantage key; finance.ai_analyze also requires your own OpenAI key. Keys are supplied per request and are not provided by the actor.
• Data is not guaranteed real-time. Quotes may be delayed by the upstream provider, and results are cached in-memory for ~1 minute per process to conserve API calls. Cached responses are not shared across runs.
• One tool per Apify run. Each Apify run executes a single tool call; batching many symbols/tools in one run is not supported.
• Crypto coverage. ~50 symbols are explicitly mapped to CoinGecko IDs; unmapped symbols fall back to a lowercased-symbol lookup that may not resolve.
• Not financial advice. finance.ai_analyze produces AI-generated, non-deterministic commentary for informational purposes only. It is not investment advice and may be inaccurate.

License

MIT