# mcp-stock-research

A lightweight [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that provides stock research tools powered by [yfinance](https://github.com/ranaroussi/yfinance). Works with any MCP-compatible client, including GitHub Copilot in VS Code.

Supports **Japanese stocks** (TSE) and **US stocks** out of the box.

## Tools

| Tool | Description |
|---|---|
| `get_stock_info` | Get current price, PE/PB ratios, dividend yield, and other fundamentals |
| `get_dividend_history` | Get dividend payment history with annual totals |
| `screen_high_dividend` | Screen multiple tickers for high-dividend quality (consecutive increases, revenue trend) |
| `get_valuation_summary` | Multi-model fair value calculation (DDM/DCF/PER/PBR/NAV) with median composite |

## Quick Start

### Option 1: VS Code + GitHub Copilot (recommended)

Add to `.vscode/mcp.json` in your workspace:

```json
{
    "servers": {
        "stock-research": {
            "type": "stdio",
            "command": "python",
            "args": ["path/to/mcp_stock_server/server.py"]
        }
    }
}
```

Then ask Copilot things like:
- "What's Toyota's current stock price?" → calls `get_stock_info("7203")`
- "Show me VYM's dividend history" → calls `get_dividend_history("VYM")`
- "Screen these for high dividends: 8306, 9433, 8591" → calls `screen_high_dividend`
- "NTTの理論株価を教えて" → calls `get_valuation_summary("9432")`

### Option 2: Install as a package

```bash
pip install -e ./mcp_stock_server
```

Then use the CLI entry point in your MCP config:

```json
{
    "servers": {
        "stock-research": {
            "type": "stdio",
            "command": "mcp-stock-research"
        }
    }
}
```

## Requirements

- Python 3.11+
- Internet connection (yfinance fetches data from Yahoo Finance)

## How it works

### Stock code resolution

- **Japanese stocks**: Enter a 4–5 digit code (e.g., `7203`) → automatically appended with `.T` for Tokyo Stock Exchange
- **US stocks**: Enter a ticker symbol as-is (e.g., `AAPL`, `VYM`)

### Example output

**`get_stock_info("7203")`**
```json
{
    "symbol": "7203.T",
    "name": "Toyota Motor Corporation",
    "sector": "Consumer Cyclical",
    "price": 2845.0,
    "currency": "JPY",
    "pe_ratio": 8.5,
    "pb_ratio": 1.1,
    "dividend_yield_pct": 2.81,
    "timestamp": "2026-04-23T10:30:00"
}
```

**`get_dividend_history("VYM")`**
```json
{
    "symbol": "VYM",
    "name": "Vanguard High Dividend Yield ETF",
    "price": 120.5,
    "dividend_yield_pct": 3.12,
    "annual_dividends": {
        "2022": 3.25,
        "2023": 3.48,
        "2024": 3.61,
        "2025": 3.72,
        "2026": 1.85
    },
    "total_payments": 18,
    "latest_dividend": {
        "date": "2026-03-25",
        "amount": 0.95
    }
}
```

## License

MIT