# Upstox Model Context Protocol (MCP) Server 🚀

An open-source implementation of Anthropic's **Model Context Protocol (MCP)** for the **Upstox API v2**. This server allows LLM-powered development agents (like Claude Desktop, Cursor, or local custom setups) to securely analyze portfolios and execute orders on the Indian Stock Market (NSE/BSE) using natural language.

---

## ⚡ Features

- **Get Profile (`get_profile`)**: Fetches active broker account metadata and verification status.
- **Get Holdings (`get_holdings`)**: Reads active long-term equity holdings and computes real-time PnL.
- **Place Order (`place_order`)**: Places standard or bracket orders (with optional Good Till Triggered (GTT) target and stop-loss legs) directly onto exchange servers.
- **Fallback Sandbox Mode**: Runs in dry-run mode automatically if API credentials are not set, allowing safe testing.

---

## 🛠️ Quick Start

### 1. Prerequisites
- Python 3.10 or higher installed on your system.
- An active Upstox Developer account (to obtain API credentials).

### 2. Installation
Clone the repository and install the dependencies:
```bash
git clone https://github.com/YOUR_USERNAME/upstox-mcp-server.git
cd upstox-mcp-server
pip install -r requirements.txt
```

### 3. Setup Credentials
Copy the example environment file and fill in your Upstox credentials:
```bash
cp .env.example .env
```
Open `.env` and enter:
```env
UPSTOX_ACCESS_TOKEN=your_real_access_token_here
UPSTOX_API_KEY=your_api_key_here
UPSTOX_API_SECRET=your_api_secret_here
```

---

## 🤖 Client Integration

### 1. Claude Desktop
Add the server configuration to your Claude Desktop config file (`~/Library/Application Support/Claude/claude_desktop_config.json`):

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

### 2. Cursor IDE
1. Open Cursor and go to **Settings > Features > MCP**.
2. Click **+ Add New MCP Server**.
3. Fill in:
   - **Name**: `upstox-mcp`
   - **Type**: `stdio`
   - **Command**: `python3 /absolute/path/to/upstox-mcp-server/upstox_mcp_server.py`
4. Click Save.

---

## 💡 Example Prompt Queries

Once connected, you can query your agent using standard English:
- *"What is my current portfolio worth on Upstox?"*
- *"Buy 5 shares of TATAMOTORS at market price."*
- *"Buy 10 shares of HAL at 3150 with a stop-loss at 3100 and a profit target of 3250."*

---

## 📄 License
MIT License. Feel free to modify, extend, and deploy.