Angel One Trading MCP Server

<div align="center">

Automated Stock Trading with VS Code and AI Assistants Like Claude

</div>

📖 Overview

Angel One MCP Server is a powerful integration that allows AI assistants in VS Code (using the Model Context Protocol) to execute stock trades on the Angel One trading platform directly. Place buy and sell orders using natural language, with your AI assistant handling the technical details.

🚀 Features

- AI-Powered Trading: Execute stock trades by simply asking your AI assistant
- Seamless Integration: Works with any MCP-compatible assistant (like GitHub Copilot)
- Real-Time Order Execution: Place market orders on Angel One instantly
- Secure Authentication: Uses TOTP-based secure authentication
- Modern Python Environment: Supports UV package manager for faster and more reliable dependency management

🔧 Setup & Installation

Prerequisites

- Angel One trading account
- Python 3.10+
- VS Code with an MCP-compatible AI assistant

Installation

1. Clone this repository:

   git clone https://github.com/yourusername/angel-one-mcp.git

   cd angel-one-mcp

   

2. Install dependencies using UV (recommended):

   # Install UV if you don't have it yet

   pip install uv

   

   # Create and activate a virtual environment with UV

   uv venv

   

   # On Windows

   .\.venv\Scripts\activate

   # On macOS/Linux

   # source .venv/bin/activate

   

   # Install dependencies with UV

   uv pip install -r requirements.txt

   

Alternatively, use traditional pip:

   pip install -r requirements.txt

   

3. Update your API credentials in .env file:

   ANGEL_ONE_API_KEY=YOUR_API_KEY

   ANGEL_ONE_API_SECRET=YOUR_API_SECRET

   ANGEL_ONE_USERNAME=YOUR_USERNAME

   ANGEL_ONE_PASSWORD=YOUR_PASSWORD

   ANGEL_ONE_TOTP_TOKEN=YOUR_TOTP_SECRET

   

4. Configure MCP.json File settings:

   "mcp": {

       "servers": {

           "AngelOneTradeServer": {

               "type": "stdio",

               "command": "uv",

               "args": [

                   "--directory",

                   "C:\\path\\to\\angel-one-mcp",

                   "run",

                   "server.py"

               ]

           }

       }

   }

   

Alternatively, if not using UV:

   "mcp": {

       "servers": {

           "AngelOneTradeServer": {

               "type": "stdio",

               "command": "python",

               "args": [

                   "C:\\path\\to\\angel-one-mcp\\server.py"

               ]

           }

       }

   }

   

💼 Usage

Once configured, you can use natural language to place trades through your AI assistant:

- Buy stocks: "Buy 10 shares of RELIANCE-EQ"
- Sell stocks: "Sell 5 shares of TCS-EQ"

> Note: Always append "-EQ" to equity stock symbols (e.g., "RELIANCE-EQ", "TCS-EQ") when placing orders.

🛠️ How It Works

Architecture

The system consists of three main components:

1. MCP Server (server.py): Handles communication between VS Code and the trading functions
2. Trading Logic (trade_on_angel_one.py): Implements the Angel One API integration
3. Master Data: Stock symbols and token mapping for the exchange

Trading Flow

1. User issues a natural language command to the AI assistant
2. Assistant calls the appropriate MCP function (buyStockFromAngelOne or sellStockFromAngelOne)
3. The function invokes the Angel One API to place the order
4. Order confirmation is returned to the assistant and displayed to the user

📋 Available Functions

Buy Stock

buyStockFromAngelOne(stock_symbol: str, quantity: int) -> str

Sell Stock

sellStockFromAngelOne(stock_symbol: str, quantity: int) -> str

🔄 Master Data Management

The system uses pre-loaded master data to map stock symbols to their exchange tokens:

- master_data.pkl: Contains the mapping between stock symbols and their tokens
- load_master_data(): Loads the mapping from disk
- find_symbol_token(): Locates the appropriate token for a given stock symbol

⚠️ Security and Trading Considerations

- API credentials should be stored in a .env file which is excluded from version control
- TOTP authentication provides an additional security layer
- Never share your API credentials or TOTP secret
- Important Note: The Angel One API has limitations on buying certain equity stocks due to exchange restrictions. Some equity orders may be rejected despite using the correct symbol format with "-EQ" suffix. This is a limitation of the Angel One API and not of this integration

🐞 Troubleshooting

Common Issues

1. Symbol Not Found Error:
- Ensure you're appending "-EQ" for equity stocks
- Check if the stock is available in the master data by examining master_data.json or master_data.pkl

2. Order Rejected by Exchange:
- Some equity stocks may be restricted by Angel One/exchange regulations
- Try with different stock or consult Angel One documentation for specific stock restrictions

3. Authentication Failure:
- Make sure your TOTP token is current and correctly configured
- Check if your Angel One credentials are valid and account is active

Handling Environment Issues

If you encounter issues with UV or Python environment:

```bash