Jupiter MCP Server
A Python MCP (Model Context Protocol) server for the Jupiter API Solana's premier DEX aggregator
Currently supports
๐ Features
- Jupiter Ultra API Integration: Execute immediate swaps on Solana
- Jupiter Trigger API Integration: Create and manage limit orders
- Secure Wallet Management: Uses your Solana private key for transactions
- Built-in Referral System: Automatically includes referral fees for development support
- Comprehensive Testing: Safe testing with mock and real trade execution
- Type-Safe: Full type annotations for Python
๐ Prerequisites
You need:
- uv โ Python dependency manager
- npx (comes with Node.js) โ Used to run envmcp for secure .env file loading
Once uv is installed, restart your shell before proceeding.
๐ 1-Click Install for Cursor
Option 1: Using .env File (Recommended - More Secure)
๐ Install with .env File โ
Note: This link only works in the Cursor app. If viewing on web, copy the link below:
cursor://anysphere.cursor-deeplink/mcp/install?name=jupiter-mcp-env&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJlbnZtY3AiLCItLWVudi1maWxlIiwifi8uZW52IiwidXZ4IiwiLS1mcm9tIiwiZ2l0K2h0dHBzOi8vZ2l0aHViLmNvbS9hcmFhNDcvanVwaXRlci1tY3AiLCJqdXBpdGVyLW1jcCJdfQ==
After installation, you'll need to update the env file path:
- Create your
.env
file at your preferred location (e.g.,~/.env
):
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
PRIVATE_KEY=your_base58_encoded_private_key_here
SOLANA_NETWORK=mainnet-beta
REQUEST_TIMEOUT=30
- Update the path in Cursor:
- Go to Tools & Integrations section in Cursor
- Click on MCP Tools
- Find jupiter-mcp-env
- Hover near the on/off switch and click the pencil icon โ๏ธ
- Replace
~/.env
with your actual env file path (e.g.,/Users/yourname/.env
) - Click Save
Option 2: With Cursor Input Prompts (Less Secure)
If you prefer to configure directly through Cursor prompts:
๐ Install with Direct Input โ
Note: This link only works in the Cursor app. If viewing on web, copy the link below:
cursor://anysphere.cursor-deeplink/mcp/install?name=jupiter-mcp&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJnaXQraHR0cHM6Ly9naXRodWIuY29tL2FyYWE0Ny9qdXBpdGVyLW1jcCIsImp1cGl0ZXItbWNwIl0sImVudiI6eyJQUklWQVRFX0tFWSI6IlJFUExBQ0VfVEhJUyIsIlNPTEFOQV9SUENfVVJMIjoiaHR0cHM6Ly9hcGkubWFpbm5ldC1iZXRhLnNvbGFuYS5jb20iLCJTT0xBTkFfTkVUV09SSyI6Im1haW5uZXQtYmV0YSIsIlJFUVVFU1RfVElNRU9VVCI6IjMwIn19
You'll be prompted to replace REPLACE_THIS
with your actual private key.
Pre-configured values:
SOLANA_RPC_URL
: https://api.mainnet-beta.solana.comSOLANA_NETWORK
: mainnet-betaREQUEST_TIMEOUT
: 30 secondsPRIVATE_KEY
: You'll need to replaceREPLACE_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)
Tool | Description | Parameters | Cost |
---|---|---|---|
get_swap_quote |
Get a swap quote and unsigned transaction | input_mint , output_mint , amount |
FREE |
execute_swap_transaction |
Execute a signed swap transaction | transaction , request_id |
PAID |
get_balances |
Get token balances for a wallet | wallet_address? |
FREE |
get_shield |
Get token security information | mints |
FREE |
search_token |
Search for tokens | query |
FREE |
๐ Trigger API (Limit Orders)
Tool | Description | Parameters | Cost |
---|---|---|---|
create_limit_order |
Create a limit order transaction | input_mint , output_mint , making_amount , taking_amount , slippage_bps? , expired_at? |
FREE |
execute_limit_order |
Execute a limit order transaction | transaction , request_id |
PAID |
cancel_limit_order |
Cancel a single limit order | order |
FREE |
cancel_limit_orders |
Cancel multiple limit orders | orders? |
FREE |
get_limit_orders |
Get active/historical limit orders | order_status , wallet_address? , input_mint? , output_mint? , page? |
FREE |
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
๐ง Alternative Installation (Development)
For local development or testing:
Prerequisites
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
"PRIVATE_KEY environment variable is required"
- Copy
env.example
to.env
and set your private key
- Copy
"Invalid PRIVATE_KEY format"
- Use base58 encoded private key (from Phantom wallet export)
Connection timeouts
- Try different RPC URL or increase
REQUEST_TIMEOUT
- Try different RPC URL or increase
๐ Ready to Trade!
Your Jupiter MCP server is ready for Solana DeFi interactions! ๐