# Finnhub MCP Server
A Model Context Protocol (MCP) server wrapping the [Finnhub API](https://finnhub.io/docs/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:
```bash
npx github:ach968/finnhub-mcp --api-key YOUR_FINNHUB_API_KEY
```
### Local Development
```bash
# 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
```json
{
"$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
```json
{
"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:**
```json
{
"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
```bash
# 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](https://finnhub.io/register).
## License
MIT
## Disclaimer
This project uses the [Finnhub API](https://finnhub.io/) but is not affiliated with, endorsed by, or connected to Finnhub in any way. Use this software at your own risk.
