npm package: @mustafa.ramx/finmcp
Description: FinMCP - Yahoo Finance MCP server (Cloud) with resilience middleware (circuit breaker, rate limiting, retries, caching) and data quality validation
Author: FinMCP contributors
Latest version: 3.0.1

# 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

```bash
npm install -g @mustafa.ramx/finmcp
```

## Quick Start

### Start Server

```bash
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:

```bash
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`:

```json
{
  "mcpServers": {
    "finmcp": {
      "command": "finmcp"
    }
  }
}
```

### Other AI Tools

**Cursor AI / Cline AI:**

```json
{
  "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](https://github.com/Steve-sy/finmcp)**

Documentation includes:
- [Complete Tool Reference](https://github.com/Steve-sy/finmcp/blob/main/docs/TOOLS.md)
- [Usage Guide with Examples](https://github.com/Steve-sy/finmcp/blob/main/docs/USAGE_GUIDE.md)
- [Configuration Guide](https://github.com/Steve-sy/finmcp/blob/main/docs/CONFIGURATION.md)
- [Architecture Details](https://github.com/Steve-sy/finmcp/blob/main/docs/ARCHITECTURE.md)
- [Data Verification Status](https://github.com/Steve-sy/finmcp/blob/main/docs/DATA_VERIFICATION.md)

## Configuration

Create a `config.json` file:

```json
{
  "rateLimit": {
    "requestsPerMinute": 60,
    "requestsPerHour": 1500
  },
  "cache": {
    "ttlQuotes": 60000,
    "maxCacheSize": 1000
  },
  "circuitBreaker": {
    "failureThreshold": 5,
    "monitoringWindow": 60000,
    "successThreshold": 3
  }
}
```

For detailed configuration options, see [Configuration Guide](https://github.com/Steve-sy/finmcp/blob/main/docs/CONFIGURATION.md).

## 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](https://github.com/Steve-sy/finmcp)
- [npm Package](https://www.npmjs.com/package/@mustafa.ramx/finmcp)
- [MCP Protocol](https://modelcontextprotocol.io/)
- [Report Issues](https://github.com/Steve-sy/finmcp/issues)