# 📈 Financial Data MCP Server

> A [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI assistants like Claude live access to stock, equities, and cryptocurrency data from Yahoo Finance.

[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-2024--11--05-orange.svg)](https://modelcontextprotocol.io)

Ask your assistant *"What's Apple trading at?"* or *"Compare AAPL, MSFT, and GOOGL"* and get real-time answers backed by market data — no copy-pasting from finance sites.

![Financial Data MCP Server demo](docs/demo.gif)

---

## ✨ Features

| Capability | Description |
|------------|-------------|
| 📊 **Stock data** | Real-time prices, P/E ratios, market cap, and historical OHLCV |
| 🏢 **Company info** | Sector, financials, dividend yields, and analyst metrics |
| ₿ **Crypto data** | Live prices and history for BTC, ETH, and major coins (24/7) |
| 📉 **Market indices** | Track the S&P 500, NASDAQ, Dow Jones, and more |
| ⚖️ **Comparison** | Compare multiple tickers side by side in one call |
| 🐍 **Lightweight** | Pure Python, Python 3.9+, only two dependencies |

## 🧰 Available Tools

| Tool | Description | Key parameters |
|------|-------------|----------------|
| `stock_price` | Current price and basic metrics | `symbol` |
| `stock_history` | Historical OHLCV data | `symbol`, `period` |
| `stock_info` | Detailed company information | `symbol` |
| `crypto_price` | Current cryptocurrency price | `symbol` (e.g. `BTC-USD`) |
| `crypto_history` | Historical cryptocurrency data | `symbol`, `period` |
| `market_summary` | Snapshot of major indices | `indices` (comma-separated) |
| `compare_stocks` | Side-by-side ticker comparison | `symbols` (comma-separated) |

> **`period` values:** `1d`, `5d`, `1mo`, `3mo`, `6mo`, `1y`, `2y`, `5y`, `10y`, `ytd`, `max`

## 📋 Prerequisites

- **Python 3.9 or newer**
- **pip** for installing dependencies
- An MCP-compatible client (e.g. [Claude Desktop](https://claude.ai/download)) to use the server interactively

## 🚀 Installation

```bash
# 1. Clone the repository
git clone https://github.com/<your-username>/financial-data-mcp-server.git
cd financial-data-mcp-server

# 2. (Recommended) create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt
```

## ▶️ Usage

Run the server directly (it communicates over stdio):

```bash
python server.py
```

Run the test suite to confirm everything works:

```bash
python test_server.py
```

### Connect to Claude Desktop

Add the server to your `claude_desktop_config.json` (see [DOCS.md](DOCS.md#connecting-to-claude-desktop) for the exact path on your OS and platform-specific notes):

```json
{
  "mcpServers": {
    "financial-data": {
      "command": "python3",
      "args": ["/absolute/path/to/financial-data-mcp-server/server.py"]
    }
  }
}
```

Restart Claude Desktop and the financial-data tools will be available.

## 💬 Example

```text
You:  Compare AAPL, MSFT, and GOOGL.

Claude (via compare_stocks):
  AAPL   $301.54   P/E 36.46
  MSFT   $411.74   P/E 24.52
  GOOGL  $363.31   P/E 27.69
```

## 🗂️ Project Structure

```
.
├── server.py            # Main MCP server implementation
├── test_server.py       # Functional tests
├── client_example.py    # Example tool calls
├── requirements.txt     # Python dependencies
├── README.md            # You are here
└── LICENSE              # MIT License
```

Full documentation — setup, Claude Desktop connection, tools, MCP protocol reference, and troubleshooting — lives in [DOCS.md](DOCS.md).

## 📡 Data Source

All data is sourced from Yahoo Finance via the [`yfinance`](https://github.com/ranaroussi/yfinance) library. This project is not affiliated with or endorsed by Yahoo. Data is provided for informational purposes only and is **not financial advice**.

## 🔒 Security

Found a vulnerability? Please review our [Security Policy](SECURITY.md) for responsible disclosure instructions.

## 📄 License

Distributed under the MIT License. See [LICENSE](LICENSE) for details.
# MCP-SERVER
# Financial-Analysis-MCP-SERVER