Yahoo Finance MCP Server

A Model Context Protocol (MCP) server exposing Yahoo Finance stock market data as tools. No API key required.

Tools

| Tool | Description | Example | |------|-------------|---------| | quote | Real-time quote (price, volume, P/E, yield) | quote(symbol: "AAPL") | | history | Historical OHLCV candles | history(symbol: "AAPL", interval: "1d") | | search | Search stocks by name/ticker | search(query: "NVIDIA") | | earnings | EPS estimates, revenue trends | earnings(symbol: "MSFT") | | financials | Income, balance sheet, cash flow | financials(symbol: "GOOGL") | | summary_detail | Bid/ask, valuation, ownership | summary_detail(symbol: "TSLA") |

Quick Start

Stdio (Hermes Agent / CLI)

# Install dependencies
npm install

# Run (stdio transport — default)
node index.js

HTTP (Docker / External Apps)

# Run with Node directly
MCP_TRANSPORT=http node index.js
# Or customize port:
MCP_TRANSPORT=http MCP_PORT=8080 node index.js
# Or run http-server.js directly:
node http-server.js

Docker

# Build
docker build -t yahoo-finance-mcp .

# Run (HTTP mode default in Docker)
docker run -p 3000:3000 yahoo-finance-mcp

# Stdio mode (for Hermes Agent on same host)
docker run -e MCP_TRANSPORT=stdio yahoo-finance-mcp

# Or with docker-compose
docker compose up -d

HTTP API

Endpoints

• GET / — Server info & usage guide
• GET /health — Health check: {"status":"ok","service":"yahoo-finance-mcp","version":"1.0.0"}
• POST /mcp — MCP JSON-RPC endpoint (stateless)

Example Request

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

Example Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "**Apple Inc.** (AAPL)\n\n**Price:** $309.54\n**Volume:** 45.2M\n..."
    }]
  }
}

List Available Tools

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

Configuration

| Env Var | Default | Description | |---------|---------|-------------| | MCP_TRANSPORT | stdio | stdio (CLI) or http (server) | | MCP_PORT | 3000 | Port for HTTP mode | | NODE_ENV | development | Environment |

Docker Compose

services:
  yahoo-finance-mcp:
    build: .
    ports:
      - "3000:3000"
    environment:
      - MCP_TRANSPORT=http
      - MCP_PORT=3000
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      start_period: 10s
      retries: 3

Hermes MCP Integration

Add to your Hermes config (/opt/data/config.yaml):

mcp_servers:
  yahoo_finance:
    command: "node"
    args:
      - "/opt/data/yahoo-finance-mcp-server/index.js"
    transport: stdio

License

MIT