# MCP Stock Market Servers

Two Model Context Protocol (MCP) servers providing comprehensive stock market data and news for Indian (NSE) and global markets.

## 🚀 Features

### Stock Market Server (`stock_market_server.py`)
- **Real-time Stock Prices**: Get current prices for NSE and global stocks
- **Sector Analysis**: Browse stocks by industry sectors
- **Historical Data**: Retrieve historical price data with customizable periods
- **Top Performers**: Get top gainers, losers, and most active stocks from NIFTY 50
- **Intelligent Caching**: 1-hour cache system to reduce API calls
- **Fallback Data**: Backup data for major Indian stocks when APIs are unavailable

### Stock News Server (`stock_news_server.py`)
- **Stock-specific News**: Get latest news for individual stocks
- **Market News**: General market news and updates
- **Multiple Sources**: Integrates Alpha Vantage, Yahoo Finance, and NewsAPI
- **Smart Caching**: 1-hour cache system for news articles
- **Error Resilience**: Graceful fallback when API limits are reached

## 📋 Prerequisites

### Python Dependencies

#### Using UV (Recommended)
```bash
uv add fastmcp yfinance requests beautifulsoup4 pandas pathlib
```

#### Using Pip
```bash
pip install fastmcp yfinance requests beautifulsoup4 pandas pathlib
```

### API Keys (Optional but Recommended)
1. **NewsAPI** (Free tier available)
   - Visit: https://newsapi.org/
   - Get your API key
   - Set environment variable: `NEWS_API_KEY`

2. **Alpha Vantage** (Free tier available)
   - Visit: https://www.alphavantage.co/
   - Get your API key
   - Set environment variable: `ALPHA_VANTAGE_API_KEY`

### Setting Environment Variables

#### Windows (PowerShell)
```powershell
# Temporary (current session only)
$env:NEWS_API_KEY = "your_newsapi_key_here"
$env:ALPHA_VANTAGE_API_KEY = "your_alphavantage_key_here"

# Permanent
[System.Environment]::SetEnvironmentVariable('NEWS_API_KEY', 'your_newsapi_key_here', 'User')
[System.Environment]::SetEnvironmentVariable('ALPHA_VANTAGE_API_KEY', 'your_alphavantage_key_here', 'User')
```

#### Linux/macOS
```bash
# Add to ~/.bashrc or ~/.zshrc
export NEWS_API_KEY="your_newsapi_key_here"
export ALPHA_VANTAGE_API_KEY="your_alphavantage_key_here"

# Or set temporarily
export NEWS_API_KEY="your_newsapi_key_here"
export ALPHA_VANTAGE_API_KEY="your_alphavantage_key_here"
```

## 🛠️ Installation & Setup

1. **Clone or download** the server files

2. **Install dependencies**:
   
   #### Using UV (Recommended)
   ```bash
   uv add fastmcp yfinance requests beautifulsoup4 pandas
   ```
   
   #### Using Pip
   ```bash
   pip install fastmcp yfinance requests beautifulsoup4 pandas
   ```

3. **Set API keys** (optional but recommended)

4. **Test the servers** (opens server for testing):
   
   #### Using UV
   ```bash
   # Test Stock Market Server (opens interactive testing environment)
   uv run mcp dev stock_market_server.py
   
   # Test Stock News Server (opens interactive testing environment)
   uv run mcp dev stock_news_server.py
   ```
   
   #### Using Python directly
   ```bash
   # Stock Market Server
   python stock_market_server.py
   
   # Stock News Server  
   python stock_news_server.py
   ```

5. **Install in Claude**:
   
   #### Using UV
   ```bash
   # Install Stock Market Server
   uv run mcp install stock_market_server.py
   
   # Install Stock News Server
   uv run mcp install stock_news_server.py
   ```

## 📚 Available Tools

### Stock Market Server Tools

#### `get_stock_price(ticker: str)`
Get current stock price with formatted output.

**Parameters:**
- `ticker`: Stock symbol (e.g., "RELIANCE.NS", "AAPL")

**Example:**
```
get_stock_price("RELIANCE.NS")
# Returns: "💰 Reliance Industries (RELIANCE.NS): ₹2,500.00"
```

#### `get_sector_stocks(sector: str)`
Get list of stocks in a specific sector.

**Available Sectors:**
- Information Technology
- Financial Services
- Energy
- Consumer Goods
- Healthcare

**Example:**
```
get_sector_stocks("Information Technology")
# Returns list of IT sector stocks
```

#### `get_stock_history(ticker: str, period: str, interval: str)`
Get historical stock data for analysis.

**Parameters:**
- `ticker`: Stock symbol
- `period`: Time period ('1d', '5d', '1mo', '3mo', '6mo', '1y', '2y', '5y', '10y', 'ytd', 'max')
- `interval`: Data interval ('1m', '2m', '5m', '15m', '30m', '60m', '90m', '1h', '1d', '5d', '1wk', '1mo', '3mo')

**Example:**
```
get_stock_history("RELIANCE.NS", "1mo", "1d")
# Returns JSON with historical data and summary statistics
```

#### `get_top_nse_stocks(category: str)`
Get top performing stocks from NSE NIFTY 50.

**Categories:**
- `gainers`: Top gaining stocks
- `losers`: Top losing stocks  
- `most_active`: Most actively traded stocks

**Example:**
```
get_top_nse_stocks("gainers")
# Returns JSON with NIFTY 50 data and top gaining stocks
```

### Stock News Server Tools

#### `get_stock_news(ticker: str, source: str)`
Get latest news articles for a specific stock.

**Parameters:**
- `ticker`: Stock symbol (e.g., "RELIANCE.NS")
- `source`: News source ('all', 'alpha_vantage', 'yahoo')

**Example:**
```
get_stock_news("RELIANCE.NS", "all")
# Returns JSON with news articles for Reliance
```

#### `get_market_news()`
Get latest general market news.

**Example:**
```
get_market_news()
# Returns formatted list of latest market news
```

## 🎯 Usage Examples

Once installed in Claude Desktop, you can use these tools through natural language commands:

### Stock Market Server Examples
- "Get the current price of Reliance Industries"
- "Show me IT sector stocks"
- "Get 1-month historical data for HDFC Bank"
- "What are the top gainers in NIFTY 50 today?"

### Stock News Server Examples
- "Get latest news for TCS"
- "Show me general market news"
- "What's the latest news about Infosys from all sources?"

### Sample Interactions
**User:** "What's the current price of RELIANCE.NS?"
**Claude:** Uses `get_stock_price("RELIANCE.NS")` → "💰 Reliance Industries (RELIANCE.NS): ₹2,500.00"

**User:** "Show me the top performing stocks today"
**Claude:** Uses `get_top_nse_stocks("gainers")` → Returns formatted list of top gainers

**User:** "Get me news about TCS"
**Claude:** Uses `get_stock_news("TCS.NS", "all")` → Returns latest news articles

## 🔧 Development Workflow

### Using UV (Recommended)
```bash
# Initialize project
uv init

# Add dependencies
uv add fastmcp yfinance requests beautifulsoup4 pandas

# Test servers during development (opens interactive testing environment)
uv run mcp dev stock_market_server.py
uv run mcp dev stock_news_server.py

# Install servers for production use
uv run mcp install stock_market_server.py
uv run mcp install stock_news_server.py
```

### Using Traditional Python
```bash
# Install dependencies
pip install fastmcp yfinance requests beautifulsoup4 pandas

# Run servers
python stock_market_server.py
python stock_news_server.py
```