Upstox Server

GitHub Star License: MIT Python Support MCP Version

The Official-style Upstox MCP Server provides a high-performance Model Context Protocol (MCP) integration for the Upstox Trading API. It enables AI agents like Claude Desktop, Cursor IDE, and custom LLM applications to securely access real-time Indian stock market data (NSE, BSE, MCX), perform advanced technical analysis (RSI, MACD, Bollinger Bands), and manage portfolio information in a strictly read-only mode.

Optimized for algorithmic trading, market analysis, and automated research on Nifty 50, Bank Nifty, and thousands of Indian equities.

📖 Featured on Modern AI Day: The USB Port for AI: Connecting Claude to Real-Time Market Data

🌐 Live Demo Instance: https://mcp-server-upstox.onrender.com/mcp

---

🛠️ Technical Stack

• Framework: FastMCP (MCP Python SDK)
• API Engine: FastAPI & Uvicorn
• Data Science: Pandas, NumPy
• Technical Analysis: Pandas-TA
• Client Integration: Httpx, Upstox Python SDK
• Deployment: Docker, Render

---

⚡ Quick Start (Remote BYOK)

Connect Claude Desktop to your remote instance in seconds using Bring Your Own Key (BYOK) support:

{
  "mcpServers": {
    "Upstox-Remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp-server-upstox.onrender.com/mcp",
        "--header", "X-Upstox-API-Key:YOUR_API_KEY",
        "--header", "X-Upstox-API-Secret:YOUR_API_SECRET",
        "--header", "X-Upstox-Access-Token:YOUR_ACCESS_TOKEN"
      ]
    }
  }
}

---

🚀 Features

📊 Market Data

• Live quotes - market_get_live_quote
• Search Instruments - market_search_instruments
• Historical data - market_get_historical_data (Custom ranges)
• Intraday candles - market_get_intraday_candles

📈 Technical Analysis

• Granular Indicators - Individual tools for RSI, MACD, ADX, Bollinger Bands, etc.
• Fibonacci Levels - analysis_calculate_fibonacci_levels
• Candlestick Patterns - analysis_analyze_candlestick_patterns
• Smart Context - analysis_get_technical_analysis (Super Tool)

👤 Account Management (Read-Only)

• Margin Details - account_get_user_margin
• Order Book - account_get_order_book
• Trade History - account_get_trade_history
• Portfolio - Holdings and Positions lists

🤖 MCP Native

• AI-First Design - Built specifically for AI agents
• Tool-Based Architecture - Natural language to API calls
• Multi-User Support - Secure "Bring Your Own Key" (BYOK) architecture
• Conversational Interface - No complex API knowledge needed

---

⚠️ Safety Notice

This MCP server is STRICTLY READ-ONLY
❌ No order placement
❌ No order modification
❌ No fund transfers
❌ No trading actions

Trading endpoints are intentionally excluded for your safety and security.

---

📦 Installation

Prerequisites

• Python 3.10 or higher
• Upstox Trading Account
• Upstox API credentials

1️⃣ Clone Repository

git clone https://github.com/ravikant1918/mcp-server-upstox.git
cd mcp-server-upstox

2️⃣ Create Virtual Environment (Recommended)

python -m venv venv

# On macOS/Linux
source venv/bin/activate

# On Windows
venv\Scripts\activate

3️⃣ Install Dependencies

pip install -e .

4️⃣ Verify Installation

upstox-mcp --version

---

🔐 Configuration

Getting Upstox API Credentials

1. Login to Upstox Developer Console

   • Visit: https://api.upstox.com/
   • Login with your Upstox account

2. Create an App

   • Go to "My Apps"
   • Click "Create App"
   • Fill in details:
     • App Name: "MCP Server"
     • Redirect URL: http://localhost:8000/callback
     • Select read-only permissions

3. Get API Keys

   • Note down your API Key and API Secret

4. Generate Access Token

   • Follow Upstox OAuth flow
   • Or use Upstox's token generation tool
   • Token is valid for 24 hours (needs daily refresh)

Environment Configuration

Create a .env file in the project root:

# Required
UPSTOX_ACCESS_TOKEN=your_access_token_here

# Optional (for token auto-refresh)
UPSTOX_API_KEY=your_api_key
UPSTOX_API_SECRET=your_api_secret

Security Best Practices:

• Never commit .env file to version control
• Add .env to .gitignore
• Rotate tokens regularly
• Use read-only API scopes only

---

▶️ Running the Server

Option A — Standard IO (for Claude Desktop)

Default mode for local AI agent usage:

upstox-mcp
# or
upstox-mcp --transport stdio

Option B — HTTP Mode (for Cursor or Remote Access)

Recommended for web-based AI agents:

upstox-mcp --transport http
# Server will start on http://localhost:8000

Custom port:

upstox-mcp --transport http --port 8080

Option C — Docker Deployment

Using Docker Compose (Recommended)

# Build and run
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

Using Docker CLI

# Build image
docker build -t upstox-mcp .

# Run container
docker run -d \
  -p 8000:8000 \
  --env-file .env \
  --name upstox-mcp \
  upstox-mcp

# View logs
docker logs -f upstox-mcp

# Stop container
docker stop upstox-mcp

Server will be available at: http://localhost:8000/mcp

---

🔌 MCP Client Configuration

Claude Desktop

Config Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "Upstox": {
      "command": "/absolute/path/to/venv/bin/upstox-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "UPSTOX_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Finding the absolute path:

# On macOS/Linux
which upstox-mcp

# On Windows (PowerShell)
(Get-Command upstox-mcp).Path

Cursor IDE

1. Open Cursor Settings
2. Go to Features → MCP
3. Add new server:
   • Name: Upstox
   • Type: HTTP
   • URL: http://localhost:8000/mcp

Remote MCP (via mcp-remote) — BYOK Support

For running the server remotely or in a multi-user environment (e.g., Render), you can pass your credentials via headers. This is known as Bring Your Own Key (BYOK).

{
  "mcpServers": {
    "Upstox-Remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp-server-upstox.onrender.com/mcp",
        "--header", "X-Upstox-API-Key:YOUR_API_KEY",
        "--header", "X-Upstox-API-Secret:YOUR_API_SECRET",
        "--header", "X-Upstox-Access-Token:YOUR_ACCESS_TOKEN"
      ]
    }
  }
}

[!TIP] This allows multiple users to use the same server instance securely without sharing credentials on the server side.

---

🧠 Example Prompts (For AI Agents)

Market Data Queries

"What's the current price of RELIANCE?"
"Show me OHLC data for INFY"
"Get live quote for TATAMOTORS on NSE"
"What's the volume on SBIN today?"

Technical Analysis

"Run technical analysis on BHARTIARTL"
"Show RSI and MACD for HDFCBANK"
"Is TCS in a bullish or bearish trend?"
"Find support and resistance levels for WIPRO"
"Analyze ICICIBANK with EMA-20 and EMA-50"

Intraday Analysis

"Show me 5-minute candles for RELIANCE"
"Get 1-minute chart data for INFY"
"Display 15-minute intraday data for SBIN"

Account Information

"Show my Upstox account summary"
"What's my available margin?"
"List all my holdings"
"Show my current positions and P&L"
"What's my total portfolio value?"
"How much profit/loss do I have in TRIDENT?"

Complex Analysis

"Analyze all my holdings technically and rank them by strength"
"Compare HDFC Bank vs ICICI Bank - which is better?"
"Find oversold stocks in my watchlist (RSI < 30)"
"Which of my holdings are above their 50-day EMA?"
"Show me stocks breaking resistance levels today"

---

🧰 Available MCP Tools

Category	Tool Name	Description
Market	market_get_live_quote	Last Traded Price, OHLC, Volume
Market	market_search_instruments	Search for trading symbols
Market	market_get_instrument_details	Detailed instrument metadata
Market	market_get_historical_data	Custom historical candle data
Market	market_get_intraday_candles	Real-time intraday charts
Analysis	analysis_calculate_rsi	Momentum analysis (RSI)
Analysis	analysis_calculate_macd	Trend & momentum (MACD)
Analysis	analysis_calculate_adx	Trend strength (ADX)
Analysis	analysis_calculate_moving_averages	Trend analysis (SMA/EMA)
Analysis	analysis_calculate_bollinger_bands	Volatility study
Analysis	analysis_calculate_support_resistance	Pivot-based levels
Analysis	analysis_calculate_volatility_metrics	Risk assessment (ATR)
Analysis	analysis_calculate_stochastic	Momentum oscillator
Analysis	analysis_calculate_williams_r	%R Momentum
Analysis	analysis_calculate_fibonacci_levels	Retracement levels
Analysis	analysis_analyze_candlestick_patterns	Pattern detection
Analysis	analysis_get_technical_analysis	Holistic multi-indicator report
Account	account_get_summary	Portfolio snapshot
Account	account_get_user_margin	Available funds
Account	account_get_holdings_list	Equity holdings
Account	account_get_positions_list	Active positions
Account	account_get_order_book	Daily orders
Account	account_get_trade_history	Daily executions

[!NOTE] All tools return a standardized JSON response: { "success": true, "data": ..., "error": null, "metadata": ... }.

Tool Details

get_live_quote

{
  "symbol": "RELIANCE",      # Stock symbol
  "exchange": "NSE_EQ"       # NSE_EQ or BSE_EQ (default: NSE_EQ)
}

get_intraday_candles

{
  "symbol": "INFY",
  "interval": "5minute",     # 1minute, 3minute, 5minute, 10minute, 15minute, 30minute
  "exchange": "NSE_EQ"
}

get_technical_analysis

{
  "symbol": "SBIN",
  "interval": "1day",        # 1minute, 5minute, 15minute, 30minute, 1day, 1week
  "indicators": [            # Array of indicators
    "RSI",                   # Relative Strength Index
    "MACD",                  # Moving Average Convergence Divergence
    "EMA_20",                # Exponential Moving Average (20 period)
    "EMA_50",
    "SMA_200",               # Simple Moving Average (200 period)
    "BBANDS",                # Bollinger Bands
    "VWAP",                  # Volume Weighted Average Price
    "ATR"                    # Average True Range
  ],
  "exchange": "NSE_EQ"
}

Supported Indicators:

• RSI - Momentum oscillator (14 period default)
• MACD - Trend-following indicator
• EMA_x - Exponential Moving Average (e.g., EMA_20, EMA_50, EMA_200)
• SMA_x - Simple Moving Average (e.g., SMA_50, SMA_200)
• BBANDS - Bollinger Bands (volatility)
• VWAP - Volume Weighted Average Price
• ATR - Average True Range (volatility)

Returns:

• Price data
• Calculated indicators
• Detected candlestick patterns
• Trend context (Bullish/Bearish/Sideways)
• Support and resistance levels

---

🏗️ Architecture

┌─────────────────┐
│   AI Agent      │  (Claude Desktop, Cursor, etc.)
│  (Claude/GPT)   │
└────────┬────────┘
         │
         │ MCP Protocol
         │
┌────────▼────────┐
│   FastMCP       │  (MCP Server Framework)
│   Server        │
└────────┬────────┘
         │
         │ Python Functions
         │
┌────────▼────────┐
│   Upstox API    │  (Read-Only Access)
│   Client        │
└────────┬────────┘
         │
         │ HTTPS
         │
┌────────▼────────┐
│   Upstox        │  (Live Market Data)
│   Backend       │
└─────────────────┘

---

📊 Technical Stack

• Framework: FastMCP (Model Context Protocol)
• API Client: Upstox Python SDK
• Technical Analysis: pandas-ta
• Web Server: Uvicorn (for HTTP mode)
• Containerization: Docker, Docker Compose

---

🔧 Troubleshooting

Common Issues

1. "Invalid token" Error

Problem: Access token expired (tokens are valid for 24 hours)

Solution:

# Generate new token from Upstox
# Update .env file with new token
# Restart the MCP server

2. "Command not found: upstox-mcp"

Problem: Package not installed or not in PATH

Solution:

# Activate virtual environment
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

# Reinstall package
pip install -e .

3. Claude Desktop Not Detecting Server

Problem: Configuration file path or format issue

Solution:

• Verify config file location
• Check JSON syntax (use a JSON validator)
• Ensure absolute path to executable
• Restart Claude Desktop

4. "No data returned" for Intraday Candles

Problem: Market closed or no recent trading activity

Solution:

• Check if market is open (9:15 AM - 3:30 PM IST, Mon-Fri)
• Try a different interval
• Verify symbol is correct

5. Rate Limiting

Problem: Too many API calls in short time

Solution:

• Add delays between requests
• Implement caching (future enhancement)
• Use batch queries when possible

---

🚧 Limitations

1. Token Expiry: Access tokens expire every 24 hours and need manual refresh
2. Read-Only: Cannot place trades (by design for safety)
3. API Rate Limits: Subject to Upstox API rate limiting
4. Market Hours: Live data only available during trading hours
5. Historical Data: Limited by Upstox API data retention policies

---

🗺️ Roadmap

Version 1.1 (Done)

• Caching layer for improved performance
• Basic candlestick pattern detection

Version 2.0 (Done) 🚀

• Granular Technical Indicators: 10+ new specialized TA tools
• Namespaced Tools: Logical grouping (market_, analysis_, account_)
• Historical Data: Custom timeframe retrieval
• Instrument Search: Find symbols by name
• JSON-Safe Response Schema: Robust serialization for all agents
• Order & Trade Tracking: Real-time access to daily activity

Version 2.1 (Done) 🚀

• BYOK Support: Pass credentials via HTTP headers
• Multi-User Support: Secure architecture for shared deployments
• Dynamic Instructions: Interactive landing page with setup guides

Version 3.0 (Planned)

• Automatic token refresh mechanism
• Database integration for long-term historical tracking
• Portfolio performance analytics
• Alert system
• Machine learning predictions

Version 3.0 (Vision)

• Machine learning predictions
• Strategy builder
• Social trading features
• Mobile app integration

---

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/ravikant1918/mcp-server-upstox.git

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .
flake8 .

---

🗺️ Roadmap

Q1 2026: Foundation & Core Analysis (Current)

• Initial MCP implementation for Upstox
• Comprehensive technical indicator tools
• Bring Your Own Key (BYOK) support for remote deployments
• Dynamic JSON configuration generator

Q2 2026: Advanced Insights

• Sector-wise market analysis tools
• Option Chain analysis (Greeks calculation)
• Corporate actions tracking (Dividends, Splits)
• Multi-instrument correlation analysis

Q3 2026: Ecosystem Expansion

• Integrated Backtesting engine wrapper
• Webhook support for real-time alerts
• Native support for more MCP clients (e.g., Goose, Windsurf)

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙌 Credits & Acknowledgments

• FastMCP - MCP server framework
• Upstox - Trading API and market data
• pandas-ta - Technical analysis indicators
• Anthropic - Claude AI and MCP protocol

---

📬 Disclaimer

IMPORTANT: This project is not affiliated with, endorsed by, or sponsored by Upstox.

Trading Disclaimer:

• Trading in stocks involves substantial risk of loss
• This tool is for informational and educational purposes only
• Not financial advice - consult a licensed financial advisor
• Past performance does not guarantee future results
• The developers are not responsible for any trading losses
• Always do your own research before making investment decisions

API Usage:

• Ensure compliance with Upstox API terms of service
• Respect API rate limits
• Use responsibly and ethically

---

📞 Support

Documentation

• Upstox API Docs
• MCP Protocol Spec
• FastMCP Guide

Get Help

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

Community

• Star ⭐ this repo if you find it useful
• Share with fellow traders
• Report bugs and suggest features
• Contribute code or documentation

---

🎯 Quick Start Summary

# 1. Clone and install
git clone https://github.com/ravikant1918/mcp-server-upstox.git
cd mcp-server-upstox
pip install -e .

# 2. Configure
echo "UPSTOX_ACCESS_TOKEN=your_token" > .env

# 3. Run
upstox-mcp

# 4. Use with Claude
# Add to Claude Desktop config, restart, and start chatting!

---

Made with ❤️ for Indian Traders

Happy Trading! 📈🚀