mcp-finnhub

Model Context Protocol (MCP) server providing comprehensive access to Finnhub 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 (free tier available)
• Claude Desktop or compatible MCP client

Installation

Option 1: Install from PyPI (coming soon)

pip install mcp-finnhub

Option 2: Install from source

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:

# 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:

{
  "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)