# Stock Price MCP Server

A FastMCP-based stock price query server providing real-time stock market data.

[![Deploy to FastMCP Cloud](https://img.shields.io/badge/Deploy%20to-FastMCP%20Cloud-blue)](https://fastmcp.cloud)

## Features

Powered by yfinance for real-time stock data:

- **`get_stock_price(symbol: str)`** - Get real-time stock price and related information
  - Supports US stocks (AAPL, GOOGL, TSLA, MSFT, etc.)
  - Supports Taiwan stocks (2330.TW, 2317.TW, etc.)
  - Returns price, change, volume, market cap, and more

- **`get_stock_history(symbol: str, period: str)`** - Get historical prices
  - Period options: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max
  - Returns OHLCV (Open, High, Low, Close, Volume) data

- **`get_stock_info(symbol: str)`** - Get detailed stock information
  - Company name, sector, country
  - Employee count, market cap, P/E ratio
  - 52-week high/low, and more

- **`greet(name: str)`** - Greeting tool

## Quick Deploy to FastMCP Cloud

### Step 1: Fork or Clone this Repository

```bash
git clone https://github.com/YOUR_USERNAME/stock-price-mcp-server.git
cd stock-price-mcp-server
```

### Step 2: Push to Your GitHub

```bash
git remote set-url origin https://github.com/YOUR_USERNAME/stock-price-mcp-server.git
git push -u origin main
```

### Step 3: Deploy to FastMCP Cloud

1. Go to [FastMCP Cloud](https://fastmcp.cloud)
2. Sign in with your GitHub account
3. Click "Create New Project"
4. Fill in project information:
   - **Name**: `stock-price-server` (or your preferred name)
   - **GitHub Repository**: Select your repository
   - **Entry Point**: `server.py:mcp`
   - **Authentication**: Choose Public or Organization only
5. Click "Deploy"

### Step 4: Use Your Server

After deployment, your server will be available at:
```
https://your-project-name.fastmcp.app/mcp
```

You can connect this server in Claude Desktop, Cursor, or other MCP clients.

## Local Development

### Requirements

- Python 3.10 or higher
- uv (recommended) or pip
- FastMCP CLI

### Install Dependencies

Using uv:
```bash
uv pip install -r requirements.txt
```

### Run the Server Locally

Start the FastMCP development server:
```bash
fastmcp dev server.py:mcp
```

The server will be available at `http://localhost:8000`

**Note**: Don't use `uv run server.py` - FastMCP servers must be run through the `fastmcp` CLI tool.

### Verify Server Configuration

Inspect the server without running it:
```bash
fastmcp inspect server.py:mcp
```

### Test the Server

After starting the server, you can test it using the test client (in a separate terminal):
```bash
uv run main.py
```

## Supported Stock Symbols

### US Stocks

- AAPL - Apple Inc.
- GOOGL - Alphabet Inc.
- TSLA - Tesla Inc.
- MSFT - Microsoft Corporation
- NVDA - NVIDIA Corporation
- META - Meta Platforms Inc.

### Taiwan Stocks

- 2330.TW - Taiwan Semiconductor
- 2317.TW - Hon Hai Precision
- 2454.TW - MediaTek
- 2412.TW - Chunghwa Telecom

### Other Markets

- 9988.HK - Alibaba (Hong Kong)
- 600519.SS - Kweichow Moutai (Shanghai)

## Usage Examples

### Using in Claude Desktop

1. Open Claude Desktop settings
2. Add MCP server:

```json
{
  "mcpServers": {
    "stock-price": {
      "url": "https://your-project-name.fastmcp.app/mcp"
    }
  }
}
```

3. Restart Claude Desktop
4. Now you can ask: "What's the stock price of AAPL?" or "Show me TSMC's price trend for the last month"

### Using FastMCP Client

```python
import asyncio
from fastmcp import Client

async def query_stock():
    client = Client("https://your-project-name.fastmcp.app/mcp")
    async with client:
        # Query real-time stock price
        result = await client.call_tool("get_stock_price", {"symbol": "AAPL"})
        print(result.data)

        # Query historical prices
        history = await client.call_tool("get_stock_history", {
            "symbol": "TSLA",
            "period": "1mo"
        })
        print(history.data)

asyncio.run(query_stock())
```

## Technical Details

- **Data Source**: Yahoo Finance (via yfinance package)
- **Update Frequency**: Real-time (15-minute delay per Yahoo Finance API limits)
- **Supported Markets**: Major global stock markets (US, Taiwan, Hong Kong, China, etc.)
- **Deployment Platform**: FastMCP Cloud
- **Auto Deployment**: Automatically redeploys on push to main branch
- **PR Preview**: Each PR gets a unique testing URL

## File Structure

```
stock-price-mcp-server/
├── server.py           # FastMCP server implementation
├── requirements.txt    # Python dependencies
├── pyproject.toml      # Project configuration
├── .gitignore         # Git ignore rules
└── README.md          # Documentation
```

## License

MIT License

## Contributing

Issues and Pull Requests are welcome!

## Support

For questions:

1. Check [FastMCP Official Documentation](https://gofastmcp.com)
2. Submit a GitHub Issue
3. Visit [FastMCP Cloud](https://fastmcp.cloud) for help