Jupiter MCP

Jupiter MCP

A Model Context Protocol server for Jupiter API, Solana's premier DEX aggregator. Supports immediate swaps through Ultra API and limit orders through Trigger API.

📦 Pre-built Desktop Extension (DXT)

Prerequisites

Before installing the extension, ensure you have:

1. Node.js and npx (for envmcp support)
   • Download from: https://nodejs.org/
   • Verify with: npx --version
2. uv/uvx (Python package manager)
   • Install from: https://docs.astral.sh/uv/getting-started/installation/
   • macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
   • Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   • Verify with: uvx --version

Once you have prereqs for easy installation in Claude Desktop:

Download jupiter-mcp-latest.dxt 📥

The DXT includes:

• ✅ One-click installation in Claude Desktop
• ✅ Automatic dependency management with uvx
• ✅ Secure environment variable configuration
• ✅ Built-in error handling and debugging

Note: The DXT file is automatically updated on every commit for the latest features and fixes.

🚀 Quick Installation Options

Option 1: Claude Desktop DXT (Recommended) 🖱️

Download the DXT file and double-click to install. See dxt/README.md for detailed instructions.

Option 2: Quick Install with Cursor 🎯

Instructions:

1. Copy the link below (click the copy button in the code block)
2. Paste it into your browser address bar or Cursor's command palette
3. Follow the prompts to complete installation
4. You'll be prompted to replace REPLACE_THIS with your actual solana private key!

🚀 Install with Direct Input:

cursor://anysphere.cursor-deeplink/mcp/install?name=jupiter-mcp&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJnaXQraHR0cHM6Ly9naXRodWIuY29tL2FyYWE0Ny9qdXBpdGVyLW1jcCIsImp1cGl0ZXItbWNwIl0sImVudiI6eyJQUklWQVRFX0tFWSI6IlJFUExBQ0VfVEhJUyIsIlNPTEFOQV9SUENfVVJMIjoiaHR0cHM6Ly9hcGkubWFpbm5ldC1iZXRhLnNvbGFuYS5jb20iLCJTT0xBTkFfTkVUV09SSyI6Im1haW5uZXQtYmV0YSIsIlJFUVVFU1RfVElNRU9VVCI6IjMwIn19

Note: These links only work in Cursor

Manual config for .env file approach:

{
  "mcpServers": {
    "jupiter-mcp": {
      "command": "npx",
      "args": [
        "envmcp",
        "--env-file",
        "/path/to/your/.env",
        "uvx",
        "--from",
        "git+https://github.com/araa47/jupiter-mcp",
        "jupiter-mcp"
      ]
    }
  }
}

Replace /path/to/your/.env with your actual env file path (e.g., /Users/yourname/.env)

Pre-configured values:

• SOLANA_RPC_URL: https://api.mainnet-beta.solana.com
• SOLANA_NETWORK: mainnet-beta
• REQUEST_TIMEOUT: 30 seconds
• PRIVATE_KEY: You'll need to replace REPLACE_THIS with your base58 encoded private key

⚡ Quick Start (MCP Configuration)

Add this to your MCP client configuration:

{
  "mcpServers": {
    "jupiter-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/araa47/jupiter-mcp",
        "jupiter-mcp"
      ],
      "env": {
        "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com",
        "PRIVATE_KEY": "${PRIVATE_KEY}",
        "SOLANA_NETWORK": "mainnet-beta",
        "REQUEST_TIMEOUT": "30"
      }
    }
  }
}

Alternative Configuration (Using .env file)

If you prefer to load environment variables from a .env file to avoid storing sensitive data in your MCP configuration:

{
  "mcpServers": {
    "jupiter-mcp": {
      "command": "npx",
      "args": [
        "envmcp",
        "--env-file",
        "${ENV_FILE_PATH}",
        "uvx",
        "--from",
        "git+https://github.com/araa47/jupiter-mcp",
        "jupiter-mcp"
      ],
      "env": {
        "ENV_FILE_PATH": ".env"
      }
    }
  }
}

This approach uses envmcp to securely load your PRIVATE_KEY from a .env file without exposing it in configuration files. Replace ENV_FILE_PATH with the absolute path to your .env file (e.g., /Users/yourname/.env or /home/user/.env).

Environment Variables Required:

• PRIVATE_KEY: Your base58 encoded Solana private key (from Phantom wallet export)
• Optional: Override SOLANA_RPC_URL if you have a custom RPC endpoint

🎉 Available Tools

💱 Ultra API (Immediate Swaps)

📊 Trigger API (Limit Orders)

Key Differences: Swaps vs Limit Orders

• Swaps (Ultra API): Execute immediately at current market price
• Limit Orders (Trigger API): Execute automatically when your target price is reached

🛠️ Development & CI/CD

Automated DXT Building

This project includes automated DXT building integrated with pre-commit hooks:

• Pre-commit Hook: Automatically builds DXT files when changes are made to dxt/ folder
• Simple Naming: Always creates jupiter-mcp-latest.dxt for easy downloads
• Auto-update: The latest DXT file is always current with the main branch

Manual DXT Build

# Build DXT
./scripts/build-dxt.sh

# Output: jupiter-mcp-latest.dxt

Pre-commit Setup

# Install pre-commit hooks (includes DXT building)
pre-commit install

# The DXT will be automatically built when changes are detected in:
# - dxt/ directory
# - scripts/build-dxt.sh

🔧 Alternative Installation (Development)

For local development or testing:

Prerequisites

• Python 3.12+
• uv for dependency management
• direnv

Setup

git clone https://github.com/araa47/jupiter-mcp
cd jupiter-mcp
direnv allow
cp .env.example .env
# Edit .env with your configuration

Environment Variables (.env file)

SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
PRIVATE_KEY=your_base58_encoded_private_key_here
SOLANA_NETWORK=mainnet-beta
REQUEST_TIMEOUT=30

Local Development Usage

# Start the server locally
uv run python run_server.py

🧪 Testing

The project includes comprehensive testing with safety features:

Test Types

🆓 Free Tests (Default - No SOL spent):

• Mock execution tests
• API quote/balance checks
• Token searches and security checks
• Error handling validation

💰 Paid Tests (Requires --run-paid-tests flag):

• Real trade execution on mainnet
• Swap tests: Uses tiny amounts (0.0001 SOL ≈ $0.015)
• Limit order tests: Creates orders 20% above market price
  • Uses 0.04 SOL (≈ $6) to meet minimum requirements
  • Orders won't execute at the high price
  • Automatically cancelled after verification
• Full transaction signing and broadcasting

Running Tests

# Safe tests only (default)
uv run pytest tests/ -v

# Include real trade execution (spends tiny amounts)
uv run pytest tests/ -v --run-paid-tests

# Test with detailed output
uv run pytest tests/ -v --run-paid-tests -s

Test Safety Features

• Paid tests clearly marked with @pytest.mark.paid
• Minimal trade amounts for real execution
• Limit orders use out-of-range prices that won't execute
• Clear warnings before spending real money
• Transaction confirmations with blockchain signatures

💡 Important Notes

Free vs Paid Operations

• 🆓 FREE: get_swap_quote, get_balances, get_shield, search_token, create_limit_order, cancel_limit_order, cancel_limit_orders, get_limit_orders - API calls only
• 💰 PAID: execute_swap_transaction, execute_limit_order - Executes real trades and spends SOL

Automatic Referral System

• All orders include a 255 basis point (2.55%) referral fee (maximum allowed)
• Referral wallet: 8cK8hCyRQCp52nVuPLnLL71afkRvRcFibSwHMjGFT8bm (Referral Dashboard)
• Note: Fees only collected for tokens with referral token accounts (currently SOL)
• Supports development and maintenance

Security

• 🔐 Private keys never leave your machine
• 🛡️ All API calls use HTTPS
• ⚠️ Never commit .env files to version control

🐛 Troubleshooting

Common Issues

1. "PRIVATE\_KEY environment variable is required"
   • Copy env.example to .env and set your private key
2. "Invalid PRIVATE\_KEY format"
   • Use base58 encoded private key (from Phantom wallet export)
3. Connection timeouts
   • Try different RPC URL or increase REQUEST_TIMEOUT

🎉 Ready to Trade!

Your Jupiter MCP server is ready for Solana DeFi interactions! 🚀