# Time Series Quant Finance MCP Server

An MCP (Model Context Protocol) server built using [FastMCP](https://github.com/jcarter-dev/fastmcp) that calculates technical analysis indicators for financial stock tickers using `yfinance` and `pandas-ta`. 

This server provides LLMs with access to real-time financial market data and quantitative analysis tools, enabling them to analyze stock trends, momentum, volatility, and key moving averages.

## Features

- **Automatic Baseline Trends**: Always includes 50-day Simple Moving Average (SMA) and 200-day SMA to establish baseline trends.
- **Multiple Technical Indicators**: Support for:
  - **RSI** (Relative Strength Index)
  - **MACD** (Moving Average Convergence Divergence)
  - **BBANDS** (Bollinger Bands)
  - **ATR** (Average True Range)
  - **SMA** (Simple Moving Average with custom lengths)
  - **EMA** (Exponential Moving Average with custom lengths)
- **Robust Multi-index Handling**: Programmatically flattens `yfinance` multi-level indices to prevent Pandas crashes.
- **JSON Output**: Returns the last 5 trading days of historical and calculated data, cleaned and formatted for easy consumption by an LLM.

---

## Installation & Setup

### Prerequisites
- Python >= 3.12
- [uv](https://github.com/astral-sh/uv) (recommended package manager) or standard `pip`

### 1. Clone & Install Dependencies

Using `uv` (recommended):
```bash
# Install dependencies using uv
uv sync
```

Or using standard `pip` and virtual environments:
```bash
# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

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

---

## Running and Debugging

### Running via FastMCP Dev Inspector
FastMCP includes a built-in development inspector that lets you interact with and test the server in a web UI.

```bash
# Using uv
uv run fastmcp dev server.py

# Or using standard python
python server.py dev
```

Alternatively, you can use the official MCP Inspector:
```bash
npx -y @modelcontextprotocol/inspector uv run server.py
```

---

## MCP Configuration

To integrate this server with client applications like **Claude Desktop**, add the configuration to your MCP settings file (typically `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows).

### Configuration using `uv` (Recommended)
```json
{
  "mcpServers": {
    "finance-server": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/mcp-finance-server",
        "server.py"
      ]
    }
  }
}
```

### Configuration using Virtual Environment Python
```json
{
  "mcpServers": {
    "finance-server": {
      "command": "/absolute/path/to/mcp-finance-server/.venv/bin/python",
      "args": [
        "/absolute/path/to/mcp-finance-server/server.py"
      ]
    }
  }
}
```

Make sure to replace `/absolute/path/to/mcp-finance-server` with the actual path to the repository on your system.

---

## Tools Reference

### `calculate_technical_indicators`

Fetches daily historical stock data for the last year and calculates requested technical indicators.

#### Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `ticker` | `string` | **Yes** | - | Stock ticker symbol (e.g. `"AAPL"`, `"MSFT"`, `"TSLA"`). |
| `requested_indicators` | `array[string]` | **Yes** | - | List of indicators to calculate. Supported values: `"RSI"`, `"MACD"`, `"BBANDS"`, `"ATR"`, `"SMA"`, `"EMA"`. |
| `rsi_length` | `integer` | No | `14` | Period length for RSI calculation. |
| `macd_fast` | `integer` | No | `12` | Fast period for MACD. |
| `macd_slow` | `integer` | No | `26` | Slow period for MACD. |
| `macd_signal` | `integer` | No | `9` | Signal period for MACD. |
| `bbands_length` | `integer` | No | `20` | Period length for Bollinger Bands. |
| `bbands_std` | `float` | No | `2.0` | Standard deviation multiplier for Bollinger Bands. |
| `atr_length` | `integer` | No | `14` | Period length for ATR. |
| `custom_sma_lengths` | `array[integer]` | No | `[]` | List of custom SMA lengths to calculate (excluding baseline 50 and 200). |
| `custom_ema_lengths` | `array[integer]` | No | `[]` | List of custom EMA lengths to calculate. |

#### Return Value
Returns a JSON-formatted string mapping date strings to indicator values for the last 5 trading days.

Example return structure (shortened for readability):
```json
{
  "2026-07-07": {
    "Open": 182.5,
    "High": 184.2,
    "Low": 181.8,
    "Close": 183.9,
    "Volume": 54200000,
    "Baseline_SMA_50": 178.4,
    "Primary_Trend_SMA_200": 170.2,
    "RSI_14": 62.4
  },
  "2026-07-08": { ... },
  "2026-07-09": { ... },
  "2026-07-10": { ... },
  "2026-07-11": { ... }
}
```