Yahoo Finance MCP Server

Production-grade financial data infrastructure for AI assistants

---

Overview

Transforms unreliable financial APIs into dependable data sources with enterprise-grade resilience, comprehensive data quality validation, and production-ready monitoring.

Built for: AI assistants, investment platforms, algorithmic trading systems, and financial research tools

Key Features:

• ✅ Circuit breaker pattern with automatic recovery
• ✅ Multi-strategy rate limiting (token bucket + adaptive + per-endpoint)
• ✅ Data quality scoring with completeness and integrity validation
• ✅ Comprehensive caching with graceful fallback
• ✅ 13+ financial data tools covering stocks, crypto, and forex
• ✅ Enterprise-grade testing (unit, integration, e2e, chaos)

---

Quick Start

Installation

Via npm (Recommended):

npm install -g yfnhanced-mcp

From source:

# Clone and install
git clone https://github.com/kanishka-namdeo/yfnhanced-mcp.git
cd yfnhanced-mcp
npm install

# Build TypeScript
npm run build

Start Server

# If installed globally via npm
yfnhanced-mcp

# Or if running from source
npm start

Claude Desktop Integration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "yfnhanced": {
      "command": "yfnhanced-mcp"
    }
  }
}

Or if running from source:

{
  "mcpServers": {
    "yfnhanced": {
      "command": "node",
      "args": ["absolute:\\path\\to\\yfnhanced-mcp\\dist\\index.js"],
      "cwd": "absolute:\\path\\to\\yfnhanced-mcp"
    }
  }
}

Usage with Other AI Tools

Cursor AI:

Add to Cursor's MCP settings:

{
  "mcpServers": {
    "yfnhanced": {
      "command": "yfnhanced-mcp"
    }
  }
}

Cline AI:

Add to Cline's MCP configuration:

{
  "mcpServers": {
    "yfnhanced": {
      "command": "yfnhanced-mcp"
    }
  }
}

Custom Integration:

Use the MCP SDK to integrate with any AI assistant:

import { Client } from '@modelcontextprotocol/sdk';

const client = new Client({
  name: 'your-app',
  version: '1.0.0',
});

await client.connect({
  command: 'yfnhanced-mcp',
});

// Use financial data tools
const quote = await client.callTool({
  name: 'get_quote',
  arguments: { symbol: 'AAPL' }
});

---

Documentation

Document	Description
TOOLS.md	Complete reference for all 13+ MCP tools
USAGE_GUIDE.md	Practical guide with examples and patterns
CONFIGURATION.md	Detailed configuration guide with best practices
ARCHITECTURE.md	Deep dive into resilience patterns and architecture
DATA_VERIFICATION.md	Verification of data availability and limitations

---

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

Note: See DATA_VERIFICATION.md for data availability status

---

Quick Reference

What Works ✅

• Real-time quotes (price, volume, market cap, etc.)
• Historical OHLCV data with integrity validation
• Company profiles and business information
• Earnings data with surprise analysis
• Analyst ratings and target prices
• Company news with metadata
• Options chains with Greeks
• Major holders information
• Trending symbols and stock screener

Known Issues ⚠️

• Financial Statements: May encounter validation errors for some symbols

  • See DATA_VERIFICATION.md for workarounds

• Crypto/Forex: Tools exist but return placeholder data

  • See DATA_VERIFICATION.md for alternatives

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

---

Configuration

For detailed configuration options, see CONFIGURATION.md.

Quick Configuration

Create config.json:

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

---

Testing

npm test              # All tests
npm run test:coverage  # With coverage report
npm run lint         # Code quality checks
npm run typecheck     # TypeScript validation

Test suites include:

• Unit tests (95%+ coverage for core middleware)
• Integration tests (full tool and resource workflows)
• End-to-end tests (complete user journeys)
• Chaos tests (network failures, API changes, partial data)

---

Development

Scripts

npm run dev         # Watch mode for development
npm run build       # Compile TypeScript
npm run start       # Start server
npm run test        # Run tests
npm run test:watch   # Watch mode for tests
npm run lint        # Run linter
npm run lint:fix    # Fix linting issues
npm run typecheck   # Type checking

Project Structure

src/
├── config/          # Configuration management
├── middleware/      # Rate limiting, caching, circuit breaker, retry
├── prompts/         # Pre-built financial analysis prompts
├── schemas/         # Zod validation schemas
├── services/        # Yahoo Finance API client
├── tools/           # MCP tool implementations (13+ tools)
├── types/           # TypeScript type definitions
├── utils/           # Data quality, formatting, security
└── index.ts         # Server entry point

For architecture details, see ARCHITECTURE.md.

---

Comparison

Feature	This Implementation	Typical Python MCP
Circuit Breaker	✅ Full 3-state implementation	❌ None
Rate Limiting	✅ Token bucket + adaptive + per-endpoint	⚠️ Simple fixed limit
Retry Logic	✅ Exponential backoff + jitter	⚠️ Linear or none
Data Quality	✅ Completeness + integrity + recommendations	❌ None
Observability	✅ Metrics + logging + stats	⚠️ Basic logging
Testing	✅ Unit + integration + e2e + chaos	⚠️ Unit only
Type Safety	✅ TypeScript compile-time checks	❌ Runtime only
Performance	✅ <500ms cold start	⚠️ 2-3s cold start
Configuration	✅ JSON/YAML with validation	⚠️ Environment variables
Security	✅ Input validation + output sanitization	❌ None

---

Contributing

Contributions welcome! Please ensure:

1. TypeScript compilation passes (npm run typecheck)
2. Linting passes (npm run lint)
3. Tests added for new features (npm test)
4. Documentation updated for API changes
5. Chaos tests added for resilience features

---

License

MIT

---

Support

• Yahoo Finance
• MCP Protocol Documentation
• yahoo-finance2 Library
• Issue Tracker

---

Documentation Index

Getting Started:

• Quick Start Guide
• Installation
• Claude Desktop Setup

Using the Server:

• Basic Usage Examples
• Advanced Patterns
• Real-World Use Cases

Reference:

• All Tools
• Configuration Options
• Architecture Details
• Data Verification

Best Practices:

• Performance Optimization
• Error Handling
• Security Guidelines