📈 MCP Stock Quotes Server

Empower your AI assistants with real-time financial market data.

This Model Context Protocol (MCP) server seamlessly bridges the gap between LLMs (like Claude, Gemini, etc.) and Yahoo Finance, enabling intelligent agents to access, analyze, and discuss live stock market trends, historical data, and financial metrics.

📖 Table of Contents

• Why Use This?
• Features
• Quick Start
• Installation
• Usage
• Available MCP Tools
• Example Interaction
• Integration Guide
  • Cline
  • Claude Code
  • Gemini CLI
• Docker Support
• Development
• API Reference
• Troubleshooting
• License

💡 Why Use This?

AI models are powerful, but they often lack real-time knowledge. By connecting them to this MCP server, you unlock their ability to:

• Analyze Market Trends: "Compare the P/E ratio of Apple vs. Microsoft."
• Track Portfolios: "What is the current value of 10 shares of NVDA?"
• Research Companies: "Get me the latest market cap and 52-week range for Tesla."
• Contextualize News: "How did the latest earnings report affect Google's stock price today?"

It transforms your AI from a static text generator into a dynamic financial analyst.

🚀 Features

• Real-time Data: Instant access to prices, volume, market cap, and more via Yahoo Finance.
• Smart Caching: Built-in caching (5min for quotes, 30min for search) to optimize performance and reduce API limits.
• Dual Transport: Supports stdio (for local CLIs) and HTTP/SSE (for remote/web clients).
• Secure & Robust: HTTP transport includes helmet security headers and rate limiting (120 req/min).
• Smart Search: Fuzzy search for stocks by company name or ticker symbol.
• Multi-Asset Support: Works with Stocks, ETFs, Cryptocurrencies, and Indices.
• Type-Safe: Built with 100% TypeScript for reliability.
• Production Ready: Includes Docker support, structured JSON logging (Winston), CI/CD pipelines, and comprehensive testing.
• Health Monitoring: Built-in health check endpoint for monitoring server status.
• Flexible Field Selection: Optional field filtering for stock quotes to reduce response size.

⚡ Quick Start

The fastest way to run the server is using npx:

# Start in Stdio Mode (default for most MCP clients)
npx stockquotes-mcp --transport stdio

# Start as an HTTP/SSE Server
npx stockquotes-mcp --transport http

Alternatively, for local development:

# Clone and Install
git clone https://github.com/lionelschiepers/StockQuotes.MCP.git
cd StockQuotes.MCP
npm install

# Build and Start
npm run build
npm run start:stdio

🛠 Installation

Prerequisites

• Node.js 24.0.0 or higher
• npm 9.0.0 or higher

Step-by-Step

1. Clone the repository

   git clone https://github.com/lionelschiepers/StockQuotes.MCP.git
   cd StockQuotes.MCP

2. Install dependencies

   npm install

3. Build the project

   npm run build

🚦 Usage

Command Line Options

| Command | Description | | :-------------------- | :-------------------------------------------------------------------- | | npm run start:stdio | Starts server with Standard I/O transport (Best for local AI agents). | | npm run start:http | Starts server with HTTP transport on port 3000. | | npm run dev | Runs in development mode with hot-reloading. |

Available MCP Tools

Your AI agent will have access to the following tools:

1. get_stock_quote

Fetches detailed financial data for a specific ticker.

• Parameters:
  • ticker (required): Stock ticker symbol (e.g., AAPL, GOOGL, MSFT)
  • fields (optional): Array of specific fields to return (e.g., ["regularMarketPrice", "marketCap"])
• Example Prompt: "What is the price of AAPL?"
• Returns: Price, Currency, Market Cap, Exchange, P/E ratio, 52-week range, and other key metrics.

2. search_stocks

Finds ticker symbols based on company names.

• Parameters:
  • query (required): Search query (company name or ticker)
• Example Prompt: "Find the ticker for 'Hims & Hers'."
• Returns: List of matching symbols, names, and exchanges.

3. get_historical_data

Fetches historical stock data for a specific date range.

• Parameters:
  • ticker (required): Stock ticker symbol (e.g., AAPL)
  • fromDate (required): Start date in YYYY-MM-DD format
  • toDate (required): End date in YYYY-MM-DD format
  • fields (optional): Array of specific fields to return (e.g., ["date", "close", "high", "low", "volume"])
• Constraints: Date range cannot exceed 5 years
• Example Prompt: "Get AAPL historical data from 2024-01-01 to 2024-01-31."
• Returns: Array of daily data including date, high, low, close, and volume.

💬 Example Interaction

Here is a real-world example of how an AI assistant (like Gemini) uses this MCP server to perform data analysis:

User Prompt:

"Using stock-quotes: Calculate the average price of AAPL for the last 200, 50 and 20 days. Output is {[{days, average}]}. Keep only 2 decimals for the numbers."

AI Response:

[
  {
    "days": 200,
    "average": 233.12
  },
  {
    "days": 50,
    "average": 272.62
  },
  {
    "days": 20,
    "average": 270.57
  }
]

🤖 Integration with AI Platforms

Cline

To use with Cline, add this to your MCP settings file:

{
  "mcpServers": {
    "stock-quotes": {
      "command": "npx",
      "args": ["-y", "stockquotes-mcp", "--transport", "stdio"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Claude Code

Integrate with Claude Code:

Method 1: CLI Run the following command and follow the prompts:

Linux

claude mcp add --transport stdio stockquotes-mcp -- npx -y stockquotes-mcp --transport stdio

Windows

claude mcp add --transport stdio stockquotes-mcp -- cmd /c npx -y stockquotes-mcp --transport stdio

Method 2: Manual Configuration Edit your global Claude settings (usually ~/.claude.json or ~/.claude/settings.json):

Linux

{
  "mcpServers": {
    "stock-quotes": {
      "command": "npx",
      "args": ["-y", "stockquotes-mcp", "--transport", "stdio"]
    }
  }
}

Windows

{
  "mcpServers": {
    "stock-quotes": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "stockquotes-mcp", "--transport", "stdio"]
    }
  }
}

Gemini CLI

Integrate with the Gemini CLI tool:

Method 1: Direct Command

gemini mcp add stock-quotes npx "-y stockquotes-mcp --transport stdio"

Method 2: Settings Configuration Edit your ~/.gemini/settings.json:

// CLI
{
  "mcpServers": {
    "stock-quotes": {
      "command": "npx",
      "args": ["-y", "stockquotes-mcp", "--transport", "stdio"]
    }
  }
}

// HTTP
{
  "mcpServers": {
    "stock-quotes": {
      "httpUrl": "http://servername:port/mcp",
      "headers": {
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

🐳 Docker Usage

Run the server in an isolated container.

Build:

docker build -t stockquotes-mcp:latest .

Run (HTTP Mode):

docker run -p 3000:3000 stockquotes-mcp:latest

Health Check:

The Docker container includes a health check endpoint at /health that runs every 30 seconds.

💻 Development

Project Structure

StockQuotes.MCP/
├── src/                          # Source code
│   ├── index.ts                  # Main entry point
│   ├── server.ts                 # MCP server implementation
│   ├── stockQuotesService.ts     # Business logic for stock data
│   ├── yahooFinanceClient.ts     # Yahoo Finance API client
│   ├── toolRegistration.ts      # MCP tool registration
│   ├── types.ts                  # TypeScript types and Zod schemas
│   ├── logger.ts                 # Winston logger configuration
│   ├── errors.ts                 # Custom error classes
│   └── transports/               # Transport strategies
│       ├── TransportStrategy.ts  # Transport interface
│       ├── StdioTransportStrategy.ts
│       ├── HttpTransportStrategy.ts
│       └── TransportFactory.ts
├── tests/                        # Jest tests
├── .github/                      # CI/CD Workflows
├── docs/                         # Documentation
└── dist/                         # Compiled JavaScript (generated)

Available Scripts

| Command | Description | |---------|-------------| | npm run build | Compile TypeScript to JavaScript | | npm run build:watch | Compile in watch mode | | npm run start | Start the server (requires transport flag) | | npm run start:stdio | Start with stdio transport | | npm run start:http | Start with HTTP transport on port 3000 | | npm run dev | Run in development mode with hot-reloading | | npm run inspect | Run with MCP inspector for debugging | | npm test | Run all tests | | npm run test:coverage | Run tests with coverage report | | npm run test:watch | Run tests in watch mode | | npm run lint | Run ESLint to check code quality | | npm run lint:fix | Fix ESLint issues automatically | | npm run format | Format code with Prettier | | npm run format:check | Check code formatting | | npm run check | Run both lint and format checks | | npm run fix | Fix both lint and format issues | | npm run clean | Remove the dist directory |

Quality Checks

• Test: npm test (Jest with 50% coverage threshold)
• Lint: npm run lint (ESLint with TypeScript support)
• Format: npm run format (Prettier)

📚 API Reference

HTTP Endpoints

When running in HTTP mode, the server exposes the following endpoints:

POST /mcp

Main MCP endpoint for tool invocations using the Streamable HTTP transport.

Request Body: JSON-RPC 2.0 formatted requests

Response: JSON-RPC 2.0 formatted responses

GET /health

Health check endpoint for monitoring server status.

Response:

{
  "status": "healthy",
  "name": "stock-quotes-server",
  "version": "1.0.0"
}

Command Line Arguments

| Argument | Short | Description | Default | |----------|-------|-------------|---------| | --transport | -t | Transport type (stdio or http) | stdio | | --http-port | | HTTP port for HTTP transport | 3000 | | --http-host | | HTTP host to bind to | 0.0.0.0 | | --help | -h | Show help message | - | | --version | -v | Show version information | - |

Error Handling

The server uses custom error types for better error handling:

• NotFoundError: Thrown when a stock ticker is not found
• RateLimitError: Thrown when API rate limits are exceeded
• ValidationError: Thrown when input validation fails (e.g., invalid date format)

🔧 Troubleshooting

Common Issues

Issue: "Port 3000 is already in use"

Solution: Either stop the process using port 3000 or specify a different port:

npm run start:http -- --http-port 8080

Issue: "Stock ticker not found"

Solution: Verify the ticker symbol is correct and try using the search_stocks tool to find the correct symbol.

Issue: "Date range cannot exceed 5 years"

Solution: The get_historical_data tool has a 5-year limit. Break your request into smaller date ranges.

Issue: Rate limiting errors

Solution: The server caches responses for 5 minutes (quotes) and 30 minutes (search). Wait for the cache to expire or use different tickers.

Debugging

Use the MCP inspector to debug tool interactions:

npm run inspect

This will start the server with the MCP inspector UI, allowing you to test tools and inspect requests/responses.

Logs

The server uses Winston for structured JSON logging. Logs are output to the console with the following levels:

• error: Critical errors that prevent normal operation
• warn: Warning messages for potential issues
• info: General informational messages
• debug: Detailed debugging information

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Yahoo Finance2 API wrapper.
• Model Context Protocol standard.

Disclaimer: This tool is for educational purposes. Data provided by Yahoo Finance may be delayed. Validate all financial data before making investment decisions.