Finnhub Server

A Model Context Protocol (MCP) server wrapping the Finnhub API for financial market data.

Features

• Earnings Calendar: Get upcoming and historical earnings announcements with EPS estimates, actuals, and revenue data
• API Key Authentication: Simple API key-based authentication via CLI or environment variables
• Type-safe: Full TypeScript support with Zod validation
• Bun-native: Optimized for Bun runtime

Installation

Using npx with GitHub (recommended)

Run directly from GitHub without cloning or installing:

npx github:ach968/finnhub-mcp --api-key YOUR_FINNHUB_API_KEY

Local Development

# Clone the repository
git clone https://github.com/ach968/finnhub-mcp.git
cd finnhub-mcp

# Install dependencies
bun install

# Run in development mode
bun run dev -- --api-key YOUR_FINNHUB_API_KEY

OpenCode Configuration

Add to your OpenCode config (~/.config/opencode/opencode.json):

Using npx with GitHub

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "finnhub": {
      "type": "local",
      "command": [
        "npx",
        "github:ach968/finnhub-mcp",
        "--api-key",
        "YOUR_FINNHUB_API_KEY"
      ],
      "enabled": true
    }
  }
}

Using Environment Variables

{
  "mcp": {
    "finnhub": {
      "type": "local",
      "command": [
        "npx",
        "github:ach968/finnhub-mcp"
      ],
      "environment": {
        "FINNHUB_API_KEY": "YOUR_API_KEY"
      },
      "enabled": true
    }
  }
}

Available Tools

finnhub.calendar.earnings

Get earnings calendar for a date range.

Parameters:

• from (optional): Start date in YYYY-MM-DD format (defaults to today)
• to (optional): End date in YYYY-MM-DD format (defaults to 7 days from start)
• symbol (optional): Filter by stock symbol (e.g., "AAPL")

Example Response:

{
  "data": [
    {
      "date": "2024-01-25",
      "symbol": "AAPL",
      "quarter": "Q1",
      "fiscalYear": 2024,
      "time": "amc",
      "eps": {
        "estimate": 2.11,
        "actual": 2.18,
        "surprise": 0.07,
        "surprisePercent": 3.32
      },
      "revenue": {
        "estimate": 117900000000,
        "actual": 119580000000,
        "surprise": 1680000000,
        "surprisePercent": 1.42
      }
    }
  ],
  "count": 1,
  "dateRange": {
    "from": "2024-01-25",
    "to": "2024-01-25"
  }
}

Time Values:

• bmo: Before Market Open
• amc: After Market Close
• dmh: During Market Hours

CLI Arguments

Argument	Environment Variable	Description
--api-key	FINNHUB_API_KEY	Finnhub API key (required)

CLI arguments take priority over environment variables.

Development

Scripts

# Development with hot reload
bun run dev

# Build for production
bun run build

# Type checking
bun run typecheck

# Run the built version
bun run start -- --api-key YOUR_KEY

Project Structure

src/
├── index.ts           # Main MCP server entry point
├── finnhub-client.ts  # Finnhub API client
└── types.ts           # TypeScript types and Zod schemas

API Key

Get your free API key from Finnhub.

License

MIT

Disclaimer

This project uses the Finnhub API but is not affiliated with, endorsed by, or connected to Finnhub in any way. Use this software at your own risk.