diaorui/jupiter-perps-mcp

Jupiter Perps MCP Server

A Model Context Protocol server that enables AI agents to trade perpetual futures on Jupiter Perpetuals (Solana).

⚠️ DISCLAIMER This software is provided for educational and research purposes only. Trading perpetual futures involves substantial risk of loss and is not suitable for all investors. You are solely responsible for any trading decisions and losses incurred. The authors and contributors assume no liability for your use of this software. Use at your own risk with funds you can afford to lose.

Features

• Market Data: Real-time prices, 24h statistics, and historical OHLCV candles
• Portfolio Management: View USDC balance, open positions, PnL, and fees
• Position Trading: Open, increase, and close leveraged positions (1.1x - 100x)
• Fee Estimation: Calculate trading costs before execution
• Transaction Safety: Automatic compute budget optimization and simulation

Supported assets: SOL, ETH, BTC

How It Works

Jupiter Perpetuals uses an oracle-based pricing model with a shared liquidity pool:

• Pricing: Trades execute at oracle prices (Signal/Chainlink/Pyth), not order book prices
• Liquidity: You trade against a pool of SOL, ETH, WBTC, USDC, USDT (not against other traders)
• Slippage Protection: MAX_SLIPPAGE_BPS protects against oracle price movement during transaction execution
• Fees:
  • Base trading fee + Price impact fee (protects liquidity providers)
  • Hourly borrow fees (instead of traditional funding rates)

This means large trades don't suffer from order book depth issues, but oracle price slippage can still occur if prices move during transaction confirmation.

Key Concepts

Position Model: Positions are identified by asset + side (e.g., "Long SOL"). You can only have one position per asset/side pair. The protocol automatically merges any additional opens into the existing position, increasing its size and adjusting entry price.

Collateral: All positions use USDC as collateral. For long positions, the protocol swaps USDC to the asset internally.

Fees: Trading fees (base + price impact) are paid when opening/increasing/closing positions. Borrow fees accrue hourly and are settled when modifying/closing. Use estimate_open_position before trading to understand total costs.

Trading: All trades execute at market price immediately (no limit orders). Tools return a transaction signature for logging purposes. The protocol processes positions asynchronously in a separate transaction - this may take a few seconds and can fail. Use get_account_portfolio to verify the position was successfully created.

Prerequisites

• Node.js 18+
• A Solana wallet with USDC for trading
• Wallet private key (base58 encoded)

Installation

git clone <repository-url>
cd jupiter-perps-mcp
npm install
npm run build

Configuration

Create a .env file:

cp .env.example .env

Required settings:

WALLET_PRIVATE_KEY=your_base58_encoded_private_key
RPC_URL=https://api.mainnet-beta.solana.com

Optional settings:

MAX_SLIPPAGE_BPS=200                    # Default: 200 (2%)
PRIORITY_FEE_MICRO_LAMPORTS=100000      # Default: 100000

Usage

Local Testing

Quick verification with MCP inspector:

npx @modelcontextprotocol/inspector node dist/index.js

With Claude Code (Local)

Create .mcp.json in your project directory:

{
  "mcpServers": {
    "jupiter-perps": {
      "command": "node",
      "args": ["/absolute/path/to/jupiter-perps-mcp/dist/index.js"]
    }
  }
}

Or use ${workspaceFolder} for relative paths:

{
  "mcpServers": {
    "jupiter-perps": {
      "command": "node",
      "args": ["${workspaceFolder}/jupiter-perps-mcp/dist/index.js"]
    }
  }
}

Remote Setup (Sandboxed Environment)

Run the MCP server as an HTTP service to isolate sensitive wallet keys from Claude Code. The wallet private key stays on the host machine, while Claude Code runs in a separate environment and can only trade through MCP tools.

1. On the host machine (with wallet access), configure .env:

MCP_PORT=3000                           # HTTP server port (default: 3000)

2. Start in HTTP mode:

npm run start:remote

Or set MCP_MODE=http in .env for deployment/automation.

3. In your sandboxed Claude Code environment, create .mcp.json:

{
  "mcpServers": {
    "jupiter-perps": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

For different machines, replace localhost with the host IP (e.g., http://192.168.1.100:3000/mcp).

Security: The server binds to localhost by default. For remote access, use SSH tunneling, VPN, or firewall rules to control access.

4. Test the connection:

curl http://localhost:3000/health

Available Tools

Market Data & Trading

Technical Indicators

Security

⚠️ Important Safety Notes

• Never commit your .env file
• Use a dedicated wallet with limited funds
• All positions use USDC as collateral
• Review transaction details before confirming
• Consider using a private RPC endpoint for production

License

MIT