MCP Finnhub Server

A comprehensive financial market data and news service powered by the Finnhub API. This MCP server provides real-time stock quotes, company profiles, financial metrics, analyst recommendations, and market news.

Features

get_market_news: Get latest market news by category (general, forex, crypto, merger)
get_stock_quote: Get real-time stock quotes with pricing and trading data
get_company_profile: Get detailed company information and profiles
get_basic_financials: Get key financial metrics and ratios
get_recommendation_trends: Get analyst recommendation trends and ratings

MCP Protocol Endpoints

GET /health - Health check endpoint
POST /mcp - Main MCP protocol endpoint for all tool interactions
Available tools accessible via MCP protocol:
- get_market_news - Get latest market news by category
- get_stock_quote - Get real-time stock quotes
- get_company_profile - Get detailed company information
- get_basic_financials - Get key financial metrics and ratios
- get_recommendation_trends - Get analyst recommendation trends

Configuration

Required Environment Variables

FINNHUB_API_KEY - Your Finnhub API key (get one free at finnhub.io)

Optional Environment Variables

PORT - Server port (default: 8000)
HOST - Server host (default: 0.0.0.0)

Development

Requirements

Python 3.13+
FastMCP 2.11.2+
uv (for dependency management)
Finnhub API key

Setup

# Install dependencies
uv sync

# Set your API key
export FINNHUB_API_KEY="your_api_key_here"

# Run tests with proper async support
uv run pytest

# Run server locally (streamable-http transport)
uv run python server.py

The server will start on http://localhost:8000 using the streamable-http transport. All tool interactions must go through the MCP protocol endpoint at /mcp.

Docker Build & Push

Use the provided Makefile for common tasks:

# Run tests
make test

# Build Docker image
make build

# Push to registry (requires Docker Hub login)
make push

# Test, build, and push
make all

# Interactive version release
make release

Manual Docker commands:

# Build image
docker build -t nimbletools/mcp-finnhub .

# Run container with API key
docker run -e FINNHUB_API_KEY="your_api_key" -p 8000:8000 nimbletools/mcp-finnhub

# Push to Docker Hub
docker push nimbletools/mcp-finnhub

Usage Examples

All tool interactions must use the MCP protocol. Here are examples of proper MCP requests:

Initialize MCP Session

First, establish an MCP session to initialize the connection:

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'

List Available Tools

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

Get Market News

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_market_news",
      "arguments": {
        "category": "general"
      }
    }
  }'

Get Stock Quote

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "get_stock_quote",
      "arguments": {
        "symbol": "AAPL"
      }
    }
  }'

Get Company Profile

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "get_company_profile",
      "arguments": {
        "symbol": "MSFT"
      }
    }
  }'

Note: Session management is required. You must initialize the MCP session before making tool calls. Each request should use unique id values to track responses properly.

Finnhub API

This server uses the Finnhub API to provide financial data. You'll need a free API key to use this service.

Free Tier Limits

60 API calls/minute
Basic stock data, news, and company information
Real-time US stock prices

Premium Features

Higher rate limits
More historical data
Advanced financial metrics
Global market coverage

About

Part of the NimbleTools ecosystem. From the makers of NimbleBrain.

License

MIT License - see LICENSE for details.

mcp-finnhub