Yahoo Finance MCP Server

Production-grade financial data infrastructure for AI assistants with enterprise-grade resilience, comprehensive data quality validation, and production-ready monitoring.

Installation

npm install -g @mustafa.ramx/finmcp

Quick Start

Start Server

finmcp

Streaming HTTP (Cloud/Docker)

FinMCP supports MCP Streaming HTTP so you can deploy once (Docker/Railway/VPS) and connect from anywhere over HTTPS.

1. Build + start HTTP server:

npm run build
npm run start:http

2. Your MCP endpoint will be available at:

• http://127.0.0.1:3333/mcp (local)
• https://<your-domain>/mcp (cloud)

Optional: protect public deployments with YF_MCP_API_KEY and connect using ...?key=YOUR_SECRET.

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "finmcp": {
      "command": "finmcp"
    }
  }
}

Other AI Tools

Cursor AI / Cline AI:

{
  "mcpServers": {
    "finmcp": {
      "command": "finmcp"
    }
  }
}

Features

• 15 Financial Data Tools: Stocks, options, crypto, forex, company intelligence, market sentiment
• Circuit Breaker Pattern: Automatic recovery from API failures
• Multi-Strategy Rate Limiting: Token bucket + adaptive + per-endpoint limiting
• Data Quality Scoring: Completeness and integrity validation
• Comprehensive Caching: Graceful fallback with high cache hit ratio (70-90%)
• Streaming HTTP Transport: Run locally or deploy to the cloud (Docker/Railway) for HTTPS access
• Optional API Key Auth: Protect public deployments with YF_MCP_API_KEY
• Enterprise Testing: Unit, integration, e2e, and chaos tests

Available Tools

Market Data

• get_quote - Real-time quotes with quality reporting
• get_historical_prices - OHLCV data with date ranges
• get_historical_prices_multi - Batch historical data

Company Intelligence

• get_quote_summary - Comprehensive company overview
• get_balance_sheet - Assets, liabilities, equity
• get_income_statement - Revenue, expenses, net income
• get_cash_flow_statement - Operating, investing, financing cash flows
• get_earnings - Quarterly earnings with estimates
• get_analysis - Analyst recommendations and price targets
• get_major_holders - Institutional and insider ownership

Market Sentiment

• get_news - Latest articles with relevance scoring
• get_options - Options chains with Greeks
• get_trending_symbols - Top movers with volume metrics
• screener - Filter stocks by 12+ criteria

Cross-Asset

• get_crypto_quote - Cryptocurrency prices
• get_forex_quote - Currency pair exchange rates

Documentation

For complete documentation including configuration, usage examples, architecture details, and best practices:

View Full Documentation on GitHub

Documentation includes:

• Complete Tool Reference
• Usage Guide with Examples
• Configuration Guide
• Architecture Details
• Data Verification Status

Configuration

Create a config.json file:

{
  "rateLimit": {
    "requestsPerMinute": 60,
    "requestsPerHour": 1500
  },
  "cache": {
    "ttlQuotes": 60000,
    "maxCacheSize": 1000
  },
  "circuitBreaker": {
    "failureThreshold": 5,
    "monitoringWindow": 60000,
    "successThreshold": 3
  }
}

For detailed configuration options, see Configuration Guide.

Performance

| Metric | Value | |--------|-------| | Quote queries | 60 requests/minute (configurable) | | Batch operations | Up to 100 symbols per request | | Cache hit ratio | 70-90% for frequently accessed symbols | | Cold start time | <500ms | | Test coverage | 95%+ for core middleware |

License

MIT

Links

• GitHub Repository
• npm Package
• MCP Protocol
• Report Issues