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.