# Upstox MCP Server: Global Model Context Protocol for Indian Equity Markets 📈
<a href="https://glama.ai/mcp/servers/@ravikant1918/mcp-server-upstox">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@ravikant1918/mcp-server-upstox/badge" />
</a>
[](https://github.com/ravikant1918/mcp-server-upstox)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io/)
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](https://medium.com/@ravikantyadav1918/the-usb-port-for-ai-how-the-upstox-mcp-server-connects-claude-to-real-time-market-data-ba179358e891)
>
> 🌐 **Live Demo Instance:** [https://mcp-server-upstox.onrender.com/mcp](https://mcp-server-upstox.onrender.com/mcp)
---
## 🛠️ Technical Stack
- **Framework:** [FastMCP](https://github.com/jlowin/fastmcp) (MCP Python SDK)
- **API Engine:** [FastAPI](https://fastapi.tiangolo.com/) & [Uvicorn](https://www.uvicorn.org/)
- **Data Science:** [Pandas](https://pandas.pydata.org/), [NumPy](https://numpy.org/)
- **Technical Analysis:** [Pandas-TA](https://github.com/twopirllc/pandas-ta)
- **Client Integration:** [Httpx](https://www.python-httpx.org/), [Upstox Python SDK](https://github.com/upstox/upstox-python)
- **Deployment:** [Docker](https://www.docker.com/), [Render](https://render.com/)
---
## ⚡ Quick Start (Remote BYOK)
Connect Claude Desktop to your remote instance in seconds using **Bring Your Own Key (BYOK)** support:
```json
{
"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
```bash
git clone https://github.com/ravikant1918/mcp-server-upstox.git
cd mcp-server-upstox
```
### 2️⃣ Create Virtual Environment (Recommended)
```bash
python -m venv venv
# On macOS/Linux
source venv/bin/activate
# On Windows
venv\Scripts\activate
```
### 3️⃣ Install Dependencies
```bash
pip install -e .
```
### 4️⃣ Verify Installation
```bash
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:
```env
# 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:
```bash
upstox-mcp
# or
upstox-mcp --transport stdio
```
### Option B — HTTP Mode (for Cursor or Remote Access)
Recommended for web-based AI agents:
```bash
upstox-mcp --transport http
# Server will start on http://localhost:8000
```
Custom port:
```bash
upstox-mcp --transport http --port 8080
```
### Option C — Docker Deployment
#### Using Docker Compose (Recommended)
```bash
# Build and run
docker-compose up -d
# View logs
docker-compose logs -f
# Stop
docker-compose down
```
#### Using Docker CLI
```bash
# 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:**
```json
{
"mcpServers": {
"Upstox": {
"command": "/absolute/path/to/venv/bin/upstox-mcp",
"args": ["--transport", "stdio"],
"env": {
"UPSTOX_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN"
}
}
}
}
```
**Finding the absolute path:**
```bash
# 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)**.
```json
{
"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`
```python
{
"symbol": "RELIANCE", # Stock symbol
"exchange": "NSE_EQ" # NSE_EQ or BSE_EQ (default: NSE_EQ)
}
```
#### `get_intraday_candles`
```python
{
"symbol": "INFY",
"interval": "5minute", # 1minute, 3minute, 5minute, 10minute, 15minute, 30minute
"exchange": "NSE_EQ"
}
```
#### `get_technical_analysis`
```python
{
"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**:
```bash
# 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**:
```bash
# 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)
- [x] Caching layer for improved performance
- [x] Basic candlestick pattern detection
### Version 2.0 (Done) 🚀
- [x] **Granular Technical Indicators**: 10+ new specialized TA tools
- [x] **Namespaced Tools**: Logical grouping (`market_`, `analysis_`, `account_`)
- [x] **Historical Data**: Custom timeframe retrieval
- [x] **Instrument Search**: Find symbols by name
- [x] **JSON-Safe Response Schema**: Robust serialization for all agents
- [x] **Order & Trade Tracking**: Real-time access to daily activity
### Version 2.1 (Done) 🚀
- [x] **BYOK Support**: Pass credentials via HTTP headers
- [x] **Multi-User Support**: Secure architecture for shared deployments
- [x] **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
```bash
# 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)
- [x] Initial MCP implementation for Upstox
- [x] Comprehensive technical indicator tools
- [x] Bring Your Own Key (BYOK) support for remote deployments
- [x] 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](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](https://upstox.com/developer/api-documentation)
- [MCP Protocol Spec](https://modelcontextprotocol.io)
- [FastMCP Guide](https://github.com/jlowin/fastmcp)
### Get Help
- **Issues**: [GitHub Issues](https://github.com/ravikant1918/mcp-server-upstox/issues)
- **Discussions**: [GitHub Discussions](https://github.com/ravikant1918/mcp-server-upstox/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
```bash
# 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! 📈🚀*
