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:

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:

cp .env.example .env

Open .env and enter:

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):

{
  "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.