# mcp-finnhub

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-2024--11--05-green.svg)](https://modelcontextprotocol.io)

Model Context Protocol (MCP) server providing comprehensive access to [Finnhub](https://finnhub.io) financial market data API. Built for AI assistants like Claude Desktop to seamlessly access real-time market data, technical indicators, fundamentals, and alternative data.

## Features

- **15 MCP Tools** covering 100+ Finnhub API endpoints
- **Real-time market data**: Quotes, candles, tick data, BBO
- **Technical analysis**: 50+ indicators, patterns, support/resistance
- **Fundamentals**: Financials, earnings, dividends, metrics
- **Alternative data**: ESG scores, social sentiment, supply chain
- **Multi-asset support**: Stocks, crypto, forex, ETFs, bonds
- **Project-based storage** with automatic CSV/JSON exports
- **Background job processing** for large datasets
- **Smart output handling** with token estimation
- **Configurable tools** - enable only what you need
- **AI-friendly errors** - Structured error responses with guidance
- **Built-in help** - Every tool supports `operation="help"` for discovery

## Quick Start

### Prerequisites

- Python 3.11 or higher
- [Finnhub API key](https://finnhub.io/register) (free tier available)
- [Claude Desktop](https://claude.ai/download) or compatible MCP client

### Installation

#### Option 1: Install from PyPI (coming soon)

```bash
pip install mcp-finnhub
```

#### Option 2: Install from source

```bash
git clone https://github.com/cfdude/mcp-finnhub.git
cd mcp-finnhub
pip install -e .
```

### Configuration

1. Create a `.env` file in your project root:

```bash
# Required
FINNHUB_API_KEY=your_api_key_here
FINNHUB_STORAGE_DIR=/path/to/storage

# Optional - Tool configuration
FINNHUB_ENABLE_TECHNICAL_ANALYSIS=true
FINNHUB_ENABLE_STOCK_MARKET_DATA=true
FINNHUB_ENABLE_NEWS_SENTIMENT=true
# ... enable/disable other tools as needed

# Optional - Performance tuning
FINNHUB_RATE_LIMIT_RPM=300  # Requests per minute (30 free, 300 premium)
FINNHUB_REQUEST_TIMEOUT=30  # Request timeout in seconds
FINNHUB_SAFE_TOKEN_LIMIT=75000  # Conservative token limit
```

2. Configure Claude Desktop to use mcp-finnhub by adding to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "finnhub": {
      "command": "mcp-finnhub",
      "env": {
        "FINNHUB_API_KEY": "your_api_key_here",
        "FINNHUB_STORAGE_DIR": "/Users/yourname/finnhub-data"
      }
    }
  }
}
```

3. Restart Claude Desktop

### First Query

Ask Claude:

> "Get me the latest quote for AAPL"

Claude will use the `finnhub_stock_market_data` tool with the `get_quote` operation to fetch Apple's real-time stock quote.

## Available Tools

### Core Trading & Analysis (3 tools)

- **`finnhub_stock_market_data`** - Quotes, candles, tick data, BBO, market status
- **`finnhub_technical_analysis`** - 50+ indicators (RSI, MACD, SMA), patterns, signals
- **`finnhub_news_sentiment`** - Company news, market news, sentiment scores

### Fundamentals & Analysis (5 tools)

- **`finnhub_stock_fundamentals`** - Financials, earnings, dividends, metrics
- **`finnhub_stock_estimates`** - Revenue/EPS estimates, price targets
- **`finnhub_stock_ownership`** - Insider trades, institutional holdings
- **`finnhub_alternative_data`** - ESG scores, social sentiment, supply chain
- **`finnhub_sec_filings`** - SEC filings, earnings transcripts

### Multi-Asset Data (4 tools)

- **`finnhub_crypto_data`** - Crypto exchanges, symbols, profiles, candles
- **`finnhub_forex_data`** - Forex rates, candles, exchanges
- **`finnhub_calendar_data`** - IPO calendar, earnings calendar, economic events
- **`finnhub_market_events`** - Market holidays, analyst upgrades/downgrades

### Management Tools (3 tools)

- **`finnhub_project_create`** - Create project workspaces
- **`finnhub_project_list`** - List all projects with statistics
- **`finnhub_job_status`** - Check background job status

## Example Workflows

### Technical Analysis Workflow

```
User: "Analyze TSLA using RSI and MACD indicators"

Claude uses:
1. finnhub_technical_analysis → get_indicator (operation=get_indicator, symbol=TSLA, indicator=rsi)
2. finnhub_technical_analysis → get_indicator (operation=get_indicator, symbol=TSLA, indicator=macd)
3. Analyzes both indicators and provides trading insights
```

### Fundamental Research Workflow

```
User: "Research MSFT - get financials, earnings, and analyst estimates"

Claude uses:
1. finnhub_stock_fundamentals → get_basic_financials (operation=get_basic_financials, symbol=MSFT)
2. finnhub_stock_fundamentals → get_earnings (operation=get_earnings, symbol=MSFT)
3. finnhub_stock_estimates → get_earnings_estimates (operation=get_earnings_estimates, symbol=MSFT)
4. Summarizes financial health and analyst outlook
```

### Multi-Asset Portfolio Workflow

```
User: "Create a project called 'my-portfolio', get quotes for AAPL, BTC-USD, and EUR/USD"

Claude uses:
1. finnhub_project_create → create (operation=create, project=my-portfolio)
2. finnhub_stock_market_data → get_quote (operation=get_quote, symbol=AAPL, project=my-portfolio)
3. finnhub_crypto_data → get_crypto_profile (operation=get_crypto_profile, symbol=BINANCE:BTCUSDT)
4. finnhub_forex_data → get_forex_rates (operation=get_forex_rates, base=EUR, project=my-portfolio)
5. All data saved to /storage/my-portfolio/ with CSV exports
```

## Tool Configuration

Control which tools are available to reduce context window usage:

```bash
# Disable tools you don't need
FINNHUB_ENABLE_CRYPTO=false
FINNHUB_ENABLE_FOREX=false
FINNHUB_ENABLE_ALTERNATIVE_DATA=false

# Core tools (always recommended)
FINNHUB_ENABLE_STOCK_MARKET_DATA=true
FINNHUB_ENABLE_TECHNICAL_ANALYSIS=true
FINNHUB_ENABLE_NEWS_SENTIMENT=true
```

## Rate Limits

- **Free tier**: 60 requests/minute
- **Basic tier**: 150 requests/minute ($49.99/month)
- **Premium tier**: 300 requests/minute
- **Enterprise tier**: Custom limits

mcp-finnhub automatically handles rate limiting with exponential backoff and retry logic.

## AI Agent Features

### Help/Discovery

Every tool supports `operation="help"` to discover available operations:

```python
finnhub_stock_fundamentals(operation="help")
# Returns all operations with required/optional params and examples
```

### Structured Errors

Errors return actionable JSON instead of stack traces:

```json
{
  "error": "invalid_operation",
  "message": "Operation 'get_data' not found",
  "valid_operations": ["get_basic_financials", "get_dividends", ...],
  "tool": "finnhub_stock_fundamentals"
}
```

## Storage Structure

Projects are stored in subdirectories:

```
FINNHUB_STORAGE_DIR/
├── my-portfolio/
│   ├── .project.json         # Project metadata
│   ├── candles/              # Historical price data
│   ├── quotes/               # Real-time quotes
│   ├── news/                 # News articles
│   ├── fundamentals/         # Financial data
│   ├── technical/            # Technical indicators
│   └── jobs/                 # Background job results
└── research-tech/
    └── ...
```

## Development

### Setup

```bash
# Clone repository
git clone https://github.com/cfdude/mcp-finnhub.git
cd mcp-finnhub

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest --cov=mcp_finnhub --cov-report=term-missing

# Lint and format
ruff check --fix .
ruff format .
```

### Running Locally

```bash
# Set environment variables
export FINNHUB_API_KEY=your_api_key
export FINNHUB_STORAGE_DIR=/tmp/finnhub-data

# Run with STDIO transport (default, for Claude Desktop)
mcp-finnhub

# Run with HTTP streaming (recommended for persistent/remote connections)
mcp-finnhub --transport http --port 8000

# Run with SSE transport (deprecated, use HTTP instead)
mcp-finnhub --transport sse --port 8000

# Custom host binding for network access
mcp-finnhub --transport http --host 0.0.0.0 --port 8125
```

#### Transport Options

| Transport | Use Case | Command |
|-----------|----------|---------|
| `stdio` | Claude Desktop, local MCP clients | `mcp-finnhub` (default) |
| `http` | Remote connections, persistent server, Claude Code | `mcp-finnhub --transport http --port 8000` |
| `sse` | Legacy SSE clients (deprecated) | `mcp-finnhub --transport sse --port 8000` |

#### Running as a Persistent Service

For HTTP transport, you can run the server as a background service:

```bash
# Using nohup (simple)
nohup mcp-finnhub --transport http --port 8000 > finnhub.log 2>&1 &

# Using systemd (Linux)
# See docs/DEPLOYMENT.md for service file examples
```

### Testing with MCP Inspector

```bash
# Install MCP inspector
npm install -g @modelcontextprotocol/inspector

# Test the server
mcp-inspector mcp-finnhub
```

## Architecture

- **FastMCP Server**: Built on MCP SDK's FastMCP for multi-transport support
- **ServerContext**: Dependency injection container managing client and utilities
- **Multi-Transport**: STDIO (default), HTTP streaming, and SSE transports
- **Async Job Processing**: Background workers for large dataset operations
- **Type Safety**: Pydantic models for all API requests/responses

See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed design documentation.

## API Reference

See [API.md](docs/API.md) for complete tool documentation with examples.

## Troubleshooting

### "Authentication failed" error
- Verify your `FINNHUB_API_KEY` is correct
- Check if your API key has expired
- Ensure you haven't exceeded rate limits

### "Tool not found" error
- Check that the tool is enabled in your configuration
- Verify tool names match exactly (case-sensitive)

### Storage permission errors
- Ensure `FINNHUB_STORAGE_DIR` exists and is writable
- Check filesystem permissions

### Rate limit errors
- Reduce `FINNHUB_RATE_LIMIT_RPM` in your configuration
- Upgrade to premium tier for higher limits

## Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) for details

## Acknowledgments

- Built with [Model Context Protocol](https://modelcontextprotocol.io)
- Powered by [Finnhub API](https://finnhub.io)
- Inspired by [mcp-fred](https://github.com/robsherman/mcp-fred) patterns

## Support

- **Issues**: [GitHub Issues](https://github.com/yourusername/mcp-finnhub/issues)
- **Documentation**: [docs/](docs/)
- **Finnhub API Docs**: [finnhub.io/docs/api](https://finnhub.io/docs/api)

---

**Made with ❤️ for the AI assistant ecosystem**