# MCP Financial Analyst

A local MCP (Model Context Protocol) server that acts as a **financial analyst**: it fetches real market data from Yahoo Finance, runs lightweight analysis (moving averages, returns, volatility), and generates price charts. No hallucinated numbers—all data comes from `yfinance`.

---

## Quick start (how to use the app)

**1. Create a venv and install dependencies**

Use a **virtual environment** so you avoid conda/base Python and Homebrew’s “externally managed” pip. Use **Python 3.12+** (MCP currently supports 3.10–3.13; 3.14 support may lag).

```bash
cd MCP_StockTool
python3.12 -m venv .venv  # or: python -m venv .venv
.venv/bin/pip install -r requirements.txt
```

If you don't have Python 3.12, install it with your package manager (e.g. Homebrew on macOS), then run the two commands above with that Python.



**2. Add the MCP server to MCP Client**

Link this MCP Server to an existing MCP Client + LLM platforms like GitHub Copilot, Cursor or Claude Desktop to use:
** Repace /absolute/path/to with location of this server on your local computer.

```json
{
  "mcpServers": {
    "financial-analyst": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/absolute/path/to/MCP_StockTool"
    }
  }
}
```

- Save. Restart Cursor (or reload the window) so it picks up the server.

**3. Use it in chat**

In the Platform / IDE of your choice, open the chat, ask things like:

- *"Fetch the last 3 months of daily data for AAPL."*
- *"Analyze MSFT from 2026-01-01 to 2026-02-01 and show me the chart and key metrics."*
- *"What’s the 30-day moving average and return for GOOGL over the last 6 months?"*

The AI will call the financial tools, get real data, and answer with numbers and (when you use analyze) a chart path. Charts are saved under `MCP_StockTool/charts/`.

---

1. **fetch_market_data** – Get OHLCV data for a ticker over a date range.
2. **analyze_and_chart** – Get the same data, compute 7-day/30-day MAs, return %, and volatility, and save a price chart.

## Requirements

- Python 3.10+
- Dependencies: `mcp`, `yfinance`, `pandas`, `matplotlib`

## Install

From the project root:

```bash
cd MCP_StockTool
pip install -r requirements.txt
```

Or with uv:

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

## Run the server (stdio)

For use by an MCP client (Cursor, Claude Desktop, etc.):

```bash
python server.py
```

The server uses **stdio** transport: the client spawns this process and talks over stdin/stdout. Do not run it interactively; the client will start it.

## MCP Client Integration

Add this MCP server in Github Copilot/Cursor/Claude Desktop so the AI can use the financial tools.

2. Add a server entry like this (adjust `path` if your project lives elsewhere):

```json
{
  "mcpServers": {
    "financial-analyst": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/absolute/path/to/MCP_StockTool",
      "env": {}
    }
  }
}
```

If you use a virtualenv or `uv`:

```json
{
  "mcpServers": {
    "financial-analyst": {
      "command": "/path/to/venv/bin/python",
      "args": ["server.py"],
      "cwd": "/absolute/path/to/MCP_StockTool"
    }
  }
}
```

Or with uv:

```json
{
  "mcpServers": {
    "financial-analyst": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "/absolute/path/to/MCP_StockTool"
    }
  }
}
```

Restart App (or reload MCP) so it picks up the server. The AI will then see **fetch_market_data** and **analyze_and_chart** as available tools.

## Tools

### fetch_market_data

- **ticker** (str): Symbol, e.g. `AAPL`, `MSFT`.
- **start_date** (str): Start date `YYYY-MM-DD`.
- **end_date** (str): End date `YYYY-MM-DD`.
- **interval** (str): `"daily"` | `"weekly"` | `"monthly"` (default `"daily"`).

Returns a JSON object with `ticker`, `start_date`, `end_date`, `interval`, `row_count`, and `data` (list of OHLCV rows). On error, returns an `error` field and empty or partial data.

### analyze_and_chart

- **ticker** (str): Symbol, e.g. `AAPL`, `MSFT`.
- **start_date** (str): Start date `YYYY-MM-DD`.
- **end_date** (str): End date `YYYY-MM-DD`.
- **interval** (str): `"daily"` | `"weekly"` | `"monthly"` (default `"daily"`).
- **output_path** (str, optional): Path for the chart image. If omitted, saves to `charts/<ticker>_<timestamp>.png`.

Returns a JSON object with:

- **chart_path**: Absolute path to the saved chart.
- **metrics**: `ma_7d`, `ma_30d` (when enough data), `return_pct`, `volatility_annual_pct`, `data_points`, `first_close`, `last_close`.
- **ticker**, **start_date**, **end_date**, **interval**.

Volatility is the **annualized standard deviation of daily (or period) returns** in percent.

## Example prompts (for the AI using this server)

- “Fetch the last 3 months of daily data for AAPL.”
- “Analyze MSFT from 2024-01-01 to 2024-12-01 and show me the chart and key metrics.”
- “What’s the 30-day moving average and return for GOOGL over the last 6 months?”

The AI will call the MCP tools with the right parameters and report back using the real data and chart path returned by the server.

## Project layout

```
MCP_StockTool/
├── pyproject.toml
├── README.md
├── server.py              # MCP entrypoint (stdio)
├── tools/
│   ├── __init__.py
│   ├── market_data.py     # fetch_market_data implementation
│   └── chart_analyzer.py  # analyze_and_chart implementation
└── charts/                # created at runtime for saved images
```

## License

Use and modify as you like. Data is from Yahoo Finance via yfinance.