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)

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

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

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

Structured Errors

Errors return actionable JSON instead of stack traces:

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

# 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

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

# 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

# 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 for detailed design documentation.

API Reference

See 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 for details

Acknowledgments

• Built with Model Context Protocol
• Powered by Finnhub API
• Inspired by mcp-fred patterns

Support

• Issues: GitHub Issues
• Documentation: docs/
• Finnhub API Docs: finnhub.io/docs/api

---

Made with ❤️ for the AI assistant ecosystem