Upstox MCP Server: Global Model Context Protocol for Indian Equity Markets 📈

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:

🚀 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

2️⃣ Create Virtual Environment (Recommended)

3️⃣ Install Dependencies

4️⃣ Verify Installation

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

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:

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

Recommended for web-based AI agents:

Custom port:

Option C — Docker Deployment

Using Docker Compose (Recommended)

Using Docker CLI

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:

Finding the absolute 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).

🧠 Example Prompts (For AI Agents)

Market Data Queries

Technical Analysis

Intraday Analysis

Account Information

Complex Analysis

🧰 Available MCP Tools

Tool Details

get_live_quote

get_intraday_candles

get_technical_analysis

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

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

2. "Command not found: upstox-mcp"

Problem: Package not installed or not in PATH

Solution:

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

🗺️ 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: developerrk1918@gmail.com

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

Made with ❤️ for Indian Traders

Happy Trading! 📈🚀