Mcp Server Upstox

Upstox MCP 服务：面向印度股票市场的全局模型上下文协议 📈

官方风格的 Upstox MCP 服务为 Upstox Trading API 提供高性能的模型上下文协议（MCP）集成。它让 Claude Desktop、Cursor IDE 等 AI Agent 以及自定义 LLM 应用能够安全地访问实时印度股票市场数据（NSE、BSE、MCX）、执行高级技术分析（RSI、MACD、布林带），并以严格只读模式管理投资组合信息。

针对 Nifty 50、Bank Nifty 和数千只印度股票的算法交易、市场分析和自动化研究进行了优化。

📖 Modern AI Day 专题报道： AI 的 USB 端口：将 Claude 连接到实时市场数据

🌐 在线演示实例： https://mcp-server-upstox.onrender.com/mcp

---

🛠️ 技术栈

• 框架： FastMCP（MCP Python SDK）
• API 引擎： FastAPI 和 Uvicorn
• 数据科学： Pandas、NumPy
• 技术分析： Pandas-TA
• 客户端集成： Httpx、Upstox Python SDK
• 部署： Docker、Render

---

⚡ 快速开始（远程 BYOK）

使用**自带密钥（BYOK）**支持，只需几秒即可将 Claude Desktop 连接到远程实例：

{
  "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"
      ]
    }
  }
}

---

🚀 功能

📊 市场数据

• 实时行情 - market_get_live_quote
• 搜索金融工具 - market_search_instruments
• 历史数据 - market_get_historical_data（自定义范围）
• 日内蜡烛图 - market_get_intraday_candles

📈 技术分析

• 细粒度指标 - RSI、MACD、ADX、布林带等指标各自提供独立工具。
• 斐波那契水平 - analysis_calculate_fibonacci_levels
• 蜡烛图形态 - analysis_analyze_candlestick_patterns
• 智能上下文 - analysis_get_technical_analysis（超级工具）

👤 账户管理（只读）

• 保证金详情 - account_get_user_margin
• 订单簿 - account_get_order_book
• 交易历史 - account_get_trade_history
• 投资组合 - 持仓和仓位列表

🤖 MCP 原生

• AI 优先设计 - 专为 AI Agent 构建
• 基于工具的架构 - 将自然语言转化为 API 调用
• 多用户支持 - 安全的“自带密钥”（BYOK）架构
• 对话式界面 - 无需掌握复杂的 API 知识

---

⚠️ 安全须知

此 MCP 服务严格为只读模式
❌ 不支持下单
❌ 不支持修改订单
❌ 不支持资金转账
❌ 不支持交易操作

为保障您的安全，我们特意排除了交易端点。

---

📦 安装

前置条件

• Python 3.10 或更高版本
• Upstox 交易账户
• Upstox API 凭据

1️⃣ 克隆仓库

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

2️⃣ 创建虚拟环境（推荐）

python -m venv venv

# On macOS/Linux
source venv/bin/activate

# On Windows
venv\Scripts\activate

3️⃣ 安装依赖项

pip install -e .

4️⃣ 验证安装

upstox-mcp --version

---

🔐 配置

获取 Upstox API 凭据

1. 登录 Upstox Developer Console

   • 访问：https://api.upstox.com/
   • 使用你的 Upstox 账户登录

2. 创建应用

   • 前往“My Apps”
   • 点击“Create App”
   • 填写详细信息：
     • 应用名称：“MCP Server”
     • 重定向 URL：http://localhost:8000/callback
     • 选择只读权限

3. 获取 API 密钥

   • 记下你的 API Key 和 API Secret

4. 生成访问令牌

   • 按照 Upstox OAuth 流程操作
   • 或使用 Upstox 的令牌生成工具
   • 令牌有效期为 24 小时（需要每天刷新）

环境配置

在项目根目录中创建一个 .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

安全最佳实践：

• 切勿将 .env 文件提交到版本控制系统
• 将 .env 添加到 .gitignore
• 定期轮换令牌
• 仅使用只读 API 权限范围

---

▶️ 运行服务

选项 A — 标准 IO（适用于 Claude Desktop）

用于本地 AI Agent 的默认模式：

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

选项 B — HTTP 模式（适用于 Cursor 或远程访问）

推荐用于基于 Web 的 AI Agent：

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

自定义端口：

upstox-mcp --transport http --port 8080

选项 C — Docker 部署

使用 Docker Compose（推荐）

# Build and run
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

使用 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

服务将在此地址提供：http://localhost:8000/mcp

---

🔌 MCP 客户端配置

Claude Desktop

配置文件位置：

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

配置：

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

查找绝对路径：

# On macOS/Linux
which upstox-mcp

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

Cursor IDE

1. 打开 Cursor 设置
2. 前往 Features → MCP
3. 添加新服务：
   • 名称：Upstox
   • 类型：HTTP
   • URL：http://localhost:8000/mcp

远程 MCP（通过 mcp-remote）— 支持 BYOK

若要在远程环境或多用户环境（例如 Render）中运行服务，可以通过请求头传递凭据。这称为自带密钥（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"
      ]
    }
  }
}

提示

这样多个用户就能安全地使用同一个服务实例，而无需在服务端共享凭据。

---

🧠 示例提示词（适用于 AI Agent）

市场数据查询

"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?"

技术分析

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

日内分析

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

账户信息

"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?"

复杂分析

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

---

🧰 可用的 MCP 工具

类别	工具名称	描述
市场	market_get_live_quote	最新成交价、OHLC、成交量
市场	market_search_instruments	搜索交易标的
市场	market_get_instrument_details	标的详细元数据
市场	market_get_historical_data	自定义历史 K 线数据
市场	market_get_intraday_candles	实时日内图表
分析	analysis_calculate_rsi	动量分析（RSI）
分析	analysis_calculate_macd	趋势与动量（MACD）
分析	analysis_calculate_adx	趋势强度（ADX）
分析	analysis_calculate_moving_averages	趋势分析（SMA/EMA）
分析	analysis_calculate_bollinger_bands	波动性分析
分析	analysis_calculate_support_resistance	基于枢轴点的水平位
分析	analysis_calculate_volatility_metrics	风险评估（ATR）
分析	analysis_calculate_stochastic	动量振荡指标
分析	analysis_calculate_williams_r	%R 动量
分析	analysis_calculate_fibonacci_levels	回撤水平位
分析	analysis_analyze_candlestick_patterns	形态检测
分析	analysis_get_technical_analysis	综合多指标报告
账户	account_get_summary	投资组合概览
账户	account_get_user_margin	可用资金
账户	account_get_holdings_list	股票持仓
账户	account_get_positions_list	活跃仓位
账户	account_get_order_book	当日订单
账户	account_get_trade_history	当日成交记录

说明

所有工具均返回标准化的 JSON 响应：{ "success": true, "data": ..., "error": null, "metadata": ... }。

工具详情

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"
}

支持的指标：

• RSI - 动量振荡指标（默认 14 个周期）
• MACD - 趋势跟踪指标
• EMA_x - 指数移动平均线（例如 EMA_20、EMA_50、EMA_200）
• SMA_x - 简单移动平均线（例如 SMA_50、SMA_200）
• BBANDS - 布林带（波动性）
• VWAP - 成交量加权平均价
• ATR - 平均真实波幅（波动性）

返回内容：

• 价格数据
• 计算出的指标
• 检测到的蜡烛图形态
• 趋势背景（看涨/看跌/横盘）
• 支撑位和阻力位

---

🏗️ 架构

┌─────────────────┐
│   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       │
└─────────────────┘

---

📊 技术栈

• 框架：FastMCP（Model Context Protocol）
• API 客户端：Upstox Python SDK
• 技术分析：pandas-ta
• Web 服务：Uvicorn（用于 HTTP 模式）
• 容器化：Docker、Docker Compose

---

🔧 故障排除

常见问题

1. “Invalid token” 错误

问题：访问令牌已过期（令牌有效期为 24 小时）

解决方案：

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

2. “Command not found: upstox-mcp”

问题：软件包未安装或不在 PATH 中

解决方案：

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

# Reinstall package
pip install -e .

3. Claude Desktop 未检测到服务

问题：配置文件路径或格式有误

解决方案：

• 确认配置文件位置
• 检查 JSON 语法（使用 JSON 验证器）
• 确保可执行文件使用绝对路径
• 重启 Claude Desktop

4. 日内蜡烛图未返回数据

问题：市场已收盘或近期没有交易活动

解决方案：

• 检查市场是否开市（印度标准时间周一至周五上午 9:15 至下午 3:30）
• 尝试其他时间间隔
• 确认标的代码正确

5. 速率限制

问题：短时间内发起了过多 API 调用

解决方案：

• 在请求之间增加延迟
• 实现缓存（未来增强功能）
• 尽可能使用批量查询

---

🚧 限制

1. 令牌过期：访问令牌每 24 小时过期，需要手动刷新
2. 只读：无法下单交易（出于安全考虑）
3. API 速率限制：受 Upstox API 速率限制约束
4. 市场交易时间：实时数据仅在交易时段提供
5. 历史数据：受 Upstox API 数据保留政策限制

---

🗺️ 路线图

版本 1.1（已完成）

• 增加缓存层，提升性能
• 基础 K 线形态检测

版本 2.0（已完成）🚀

• 精细化技术指标：新增 10 多种专业 TA 工具
• 命名空间工具：按逻辑分组（market_、analysis_、account_）
• 历史数据：自定义时间范围检索
• 标的搜索：按名称查找代码
• JSON 安全响应架构：为所有 Agent 提供可靠的序列化
• 订单与交易跟踪：实时访问每日活动

版本 2.1（已完成）🚀

• BYOK 支持：通过 HTTP 标头传递凭据
• 多用户支持：为共享部署提供安全架构
• 动态说明：提供设置指南的交互式首页

版本 3.0（计划中）

• 自动刷新令牌机制
• 集成数据库，长期跟踪历史数据
• 投资组合表现分析
• 警报系统
• 机器学习预测

版本 3.0（愿景）

• 机器学习预测
• 策略构建器
• 社交交易功能
• 移动应用集成

---

🤝 贡献

欢迎贡献！请按以下步骤操作：

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'Add some AmazingFeature'）
4. 推送到分支（git push origin feature/AmazingFeature）
5. 创建 Pull Request

开发环境设置

# 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 .

---

🗺️ 路线图

2026 年第 1 季度：基础与核心分析（当前）

• 为 Upstox 实现初始 MCP
• 全面的技术指标工具
• 支持在远程部署中自带密钥（BYOK）
• 动态 JSON 配置生成器

2026 年第 2 季度：高级洞察

• 按行业划分的市场分析工具
• 期权链分析（希腊值计算）
• 公司行动跟踪（股息、拆股）
• 多标的相关性分析

2026 年第 3 季度：生态扩展

• 集成回测引擎封装器
• 支持通过 Webhook 发送实时警报
• 原生支持更多 MCP 客户端（例如 Goose、Windsurf）

---

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

---

🙌 致谢

• FastMCP - MCP 服务框架
• Upstox - 交易 API 和市场数据
• pandas-ta - 技术分析指标
• Anthropic - Claude AI 和 MCP 协议

---

📬 免责声明

重要提示：本项目与 Upstox 无关，也未获得其认可或赞助。

交易免责声明：

• 股票交易涉及重大亏损风险
• 此工具仅用于提供信息和教育目的
• 不构成财务建议——请咨询持牌财务顾问
• 过去的表现不代表未来的结果
• 开发者不对任何交易损失负责
• 做出投资决策前，请务必自行研究

API 使用：

• 请确保遵守 Upstox API 服务条款
• 遵守 API 速率限制
• 请负责任且合乎道德地使用

---

📞 支持

文档

• Upstox API 文档
• MCP 协议规范
• FastMCP 指南

获取帮助

• 问题反馈：GitHub Issues
• 讨论：GitHub Discussions
• 电子邮件：[email protected]

社区

• 如果觉得这个仓库有用，请给它点个 ⭐
• 与其他交易者分享
• 报告错误并提出功能建议
• 贡献代码或文档

---

🎯 快速入门摘要

# 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!

---

为印度交易者 ❤️ 打造

祝交易愉快！📈🚀