# 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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "query": "Apple",
  "response_format": "json"
}
```

## Local Development

### Prerequisites

- Python 3.11 or higher
- pip

### Installation

1. Clone this repository:
```bash
git clone <your-repo-url>
cd stock-mcp-server
```

2. Install dependencies:
```bash
pip install -r requirements.txt
```

3. Run the server locally (stdio mode):
```bash
python stock_mcp.py --transport stdio
```

### Testing with MCP Inspector

```bash
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:**
```bash
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](https://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:**
```json
{
  "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

```bash
docker build -t stock-mcp-server .
```

### Run Locally

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

### Test the Server

```bash
# 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](https://github.com/ranaroussi/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](https://modelcontextprotocol.io)
- Review Railway's [deployment guides](https://docs.railway.app)