Stock Data MCP Server

A Model Context Protocol (MCP) server that provides real-time stock market data through Yahoo Finance without requiring an API key. Get quotes, historical data, company information, financial statements, and more.

Features

• 🔍 Real-time Stock Quotes - Current prices, changes, volume, and market data
• 📊 Historical Data - OHLCV data with customizable periods and intervals
• 🏢 Company Information - Detailed company profiles, sectors, and metrics
• 💰 Financial Statements - Income statements, balance sheets, and cash flow
• 🔎 Ticker Search - Find ticker symbols by company name
• 🆓 No API Key Required - Uses public Yahoo Finance data via yfinance
• 🚀 Railway Ready - Deploy to Railway.app with one click

Available Tools

1. get_stock_quote

Get current stock price and trading data.

Parameters:

• symbol (string, required): Stock ticker symbol (e.g., "AAPL", "MSFT")
• response_format (string, optional): "markdown" or "json" (default: "markdown")

Example:

{
  "symbol": "AAPL",
  "response_format": "markdown"
}

2. get_stock_info

Get comprehensive company information and metrics.

Parameters:

• symbol (string, required): Stock ticker symbol
• response_format (string, optional): "markdown" or "json"

Example:

{
  "symbol": "TSLA",
  "response_format": "json"
}

3. get_stock_history

Get historical price and volume data.

Parameters:

• symbol (string, required): Stock ticker symbol
• period (string, optional): "1d", "5d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max" (default: "1mo")
• interval (string, optional): "1m", "5m", "1h", "1d", "1wk", "1mo", etc. (default: "1d")
• response_format (string, optional): "markdown" or "json"

Example:

{
  "symbol": "NVDA",
  "period": "6mo",
  "interval": "1d",
  "response_format": "json"
}

4. get_stock_financials

Get company financial statements.

Parameters:

• symbol (string, required): Stock ticker symbol
• statement_type (string, optional): "income", "balance", "cashflow" (default: "income")
• quarterly (boolean, optional): true for quarterly, false for annual (default: false)
• response_format (string, optional): "markdown" or "json"

Example:

{
  "symbol": "GOOGL",
  "statement_type": "income",
  "quarterly": false,
  "response_format": "markdown"
}

5. search_ticker

Search for ticker symbols by company name.

Parameters:

• query (string, required): Company name or partial name
• response_format (string, optional): "markdown" or "json"

Example:

{
  "query": "Apple",
  "response_format": "json"
}

Local Development

Prerequisites

• Python 3.11 or higher
• pip

Installation

1. Clone this repository:

git clone <your-repo-url>
cd stock-mcp-server

2. Install dependencies:

pip install -r requirements.txt

3. Run the server locally (stdio mode):

python stock_mcp.py --transport stdio

Testing with MCP Inspector

npx @modelcontextprotocol/inspector python stock_mcp.py

This opens a web interface where you can test all the tools interactively.

Railway Deployment

Quick Deploy

1. Push to GitHub:

git init
git add .
git commit -m "Initial commit"
git remote add origin <your-github-repo>
git push -u origin main

2. Deploy to Railway:

   • Go to railway.app
   • Click "New Project" → "Deploy from GitHub repo"
   • Select your repository
   • Railway will automatically detect the Dockerfile and deploy

3. Get Your Server URL:

   • Once deployed, Railway provides a public URL like: https://your-app.railway.app
   • Copy this URL for Claude Desktop configuration

Environment Variables

No environment variables required! This server doesn't need API keys because it uses public Yahoo Finance data.

Railway automatically sets the PORT variable - don't override it.

Claude Desktop Integration

After deploying to Railway, add this to your Claude Desktop config:

Config location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "stock-data": {
      "url": "https://your-app.railway.app",
      "transport": "streamable-http"
    }
  }
}

Replace your-app.railway.app with your actual Railway URL.

Restart Claude Desktop after saving the configuration.

Docker Usage

Build the Image

docker build -t stock-mcp-server .

Run Locally

docker run -p 8080:8080 -e PORT=8080 stock-mcp-server

Test the Server

# Health check
curl http://localhost:8080

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

Usage Examples

Get Apple Stock Quote

Request to Claude:

"What's the current price of Apple stock?"

Behind the scenes: Claude calls get_stock_quote with {"symbol": "AAPL"}

Analyze Tesla Financials

Request to Claude:

"Show me Tesla's latest income statement"

Behind the scenes: Claude calls get_stock_financials with {"symbol": "TSLA", "statement_type": "income"}

Compare Historical Performance

Request to Claude:

"Compare the 6-month performance of NVIDIA and AMD"

Behind the scenes: Claude calls get_stock_history multiple times and analyzes the data

Troubleshooting

"Unable to fetch data for symbol"

• Verify the ticker symbol is correct
• Use search_ticker to find the right symbol
• Some international stocks may not be available

Railway Deployment Issues

• Check Railway logs in the dashboard
• Verify the Dockerfile builds successfully locally
• Ensure you're not setting the PORT environment variable manually

Claude Desktop Connection Issues

1. Verify the URL has no trailing slash
2. Confirm transport is set to "streamable-http"
3. Check Claude Desktop logs (Help → View Logs)
4. Restart Claude Desktop after config changes

Data Source

This server uses yfinance, an open-source library that retrieves data from Yahoo Finance. The data is provided for informational purposes only and should not be used for trading decisions without verification.

Data Limitations:

• Real-time data may have a 15-20 minute delay
• Some international stocks may have limited data
• Historical data availability varies by symbol
• Financial statements may not be available for all companies

Architecture

Transport: SSE (Server-Sent Events) for Railway, stdio for local development Framework: FastMCP (MCP Python SDK) Data Validation: Pydantic v2 Stock Data: yfinance (Yahoo Finance API wrapper)

License

MIT License - See LICENSE file for details

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Support

For issues or questions:

• Open an issue on GitHub
• Check the MCP documentation
• Review Railway's deployment guides