What are the requirements for Finnhub MCP Server?

Finnhub MCP Server requires the following environment variables: FINNHUB_API_KEY (required). You'll also need a compatible MCP client like Claude Desktop or Claude Code.

Is Finnhub MCP Server free to use?

Yes, Finnhub MCP Server is open source and free to use. You can find the source code on GitHub.

What MCP clients support Finnhub MCP Server?

Finnhub MCP Server works with any MCP-compatible client including Claude Desktop (Anthropic's official desktop app), Claude Code (CLI tool), Cursor, and other editors with MCP support.

How do I configure Finnhub MCP Server?

Configure Finnhub MCP Server by adding it to your MCP client's config file. The setup block at the top of this page generates a ready-to-paste config for Claude Code, Cursor, Codex, Windsurf, and Claude Desktop.

MCP server/other

Finnhub MCP Server

Q: What tools does Finnhub MCP Server provide?

finnhub.calendar.earnings: Get earnings calendar for a date range..

Q: How do I install Finnhub MCP Server?

Install Finnhub MCP Server by running: npx github:ach968/finnhub-mcp --api-key YOUR_FINNHUB_API_KEY

An MCP server wrapping the Finnhub API for financial market data.

ach968/finnhub-mcp ↗by ach968updated Apr 5, 2026

Manual setup required. We don't have a verified install command for this server. Follow the maintainer README and use the raw config below as a starting point.

Prepare the server locally

Run this once before adding it to Claude Code.

git clone https://github.com/ach968/finnhub-mcp
cd finnhub-mcp

Then follow the repository README for any remaining dependency or build steps.

Add it to Claude Code

Paste the maintainer's config below, then edit any placeholder values.

~/.claude.json

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

See the finnhub-mcp README for full setup instructions.

Required:FINNHUB_API_KEY

Make your agent remember this setup

finnhub-mcp's config, env vars, and the gotchas you hit — recalled in every future Claude Code, Cursor, and Codex session.

npx conare@latest

Free · one command · indexes the sessions already on disk. Set up in the browser instead →

What it does

Retrieve upcoming and historical earnings announcements
Access EPS estimates, actuals, and revenue data
Filter earnings data by stock symbol
Simple API key-based authentication
Type-safe implementation with Zod validation

Tools 1

finnhub.calendar.earningsGet earnings calendar for a date range.

Environment Variables

FINNHUB_API_KEYrequiredFinnhub API key

Try it

→Get the earnings calendar for Apple (AAPL) for the next 7 days.

→Show me the earnings announcements for the last week.

→Retrieve the earnings report details for Microsoft (MSFT) including EPS and revenue data.

→What are the upcoming earnings announcements for this week?

Original README from ach968/finnhub-mcp

Finnhub MCP 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.

Frequently Asked Questions

What are the key features of Finnhub MCP Server?

Retrieve upcoming and historical earnings announcements. Access EPS estimates, actuals, and revenue data. Filter earnings data by stock symbol. Simple API key-based authentication. Type-safe implementation with Zod validation.

What can I use Finnhub MCP Server for?

Analyzing historical earnings performance for specific stocks. Tracking upcoming earnings release dates for a portfolio. Comparing estimated versus actual EPS for financial research. Integrating real-time financial market data into AI-driven analysis workflows.

How do I install Finnhub MCP Server?

Install Finnhub MCP Server by running: npx github:ach968/finnhub-mcp --api-key YOUR_FINNHUB_API_KEY

What MCP clients work with Finnhub MCP Server?

Finnhub MCP Server works with any MCP-compatible client including Claude Desktop, Claude Code, Cursor, and other editors with MCP support.

Conare · memory for coding agents

Turn this server into reusable context

Keep Finnhub MCP Server docs, env vars, and workflow notes in Conare so your agent carries them across sessions.

Set up free$npx conare@latest

Prepare the server locally

Add it to Claude Code

Make your agent remember this setup

What it does

Tools 1

Environment Variables

Try it

Finnhub MCP Server

Features

Installation

Using npx with GitHub (recommended)

Local Development

OpenCode Configuration

Using npx with GitHub

Using Environment Variables

Available Tools

`finnhub.calendar.earnings`

CLI Arguments

Development

Scripts

Project Structure

API Key

License

Disclaimer

Frequently Asked Questions

Turn this server into reusable context

Related MCP Servers