Jupiter MCP

1# Jupiter MCP
2 
3A Model Context Protocol server for Jupiter API, Solana's premier DEX aggregator. Supports immediate swaps through Ultra API and limit orders through Trigger API.
4 
5## 📦 Pre-built Desktop Extension (DXT)
6 
7### Prerequisites
8Before installing the extension, ensure you have:
9 
101. **Node.js and npx** (for envmcp support)
11   - Download from: https://nodejs.org/
12   - Verify with: `npx --version`
13 
142. **uv/uvx** (Python package manager)
15   - Install from: https://docs.astral.sh/uv/getting-started/installation/
16   - macOS/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
17   - Windows: `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`
18   - Verify with: `uvx --version`
19 
20 
21Once you have prereqs for easy installation in Claude Desktop:
22 
23**[Download jupiter-mcp-latest.dxt](https://github.com/araa47/jupiter-mcp/raw/main/jupiter-mcp-latest.dxt)** 📥
24 
25The DXT includes:
26- ✅ One-click installation in Claude Desktop
27- ✅ Automatic dependency management with uvx
28- ✅ Secure environment variable configuration
29- ✅ Built-in error handling and debugging
30 
31> **Note**: The DXT file is automatically updated on every commit for the latest features and fixes.
32 
33## 🚀 Quick Installation Options
34 
35### Option 1: Claude Desktop DXT (Recommended) 🖱️
36Download the DXT file and double-click to install. See `dxt/README.md` for detailed instructions.
37 
38### Option 2: Quick Install with Cursor 🎯
39 
40**Instructions:**
411. Copy the link below (click the copy button in the code block)
422. Paste it into your browser address bar or Cursor's command palette
433. Follow the prompts to complete installation
444. You'll be prompted to replace `REPLACE_THIS` with your actual solana private key!
45 
46 
47**🚀 Install with Direct Input:**
48```
49cursor://anysphere.cursor-deeplink/mcp/install?name=jupiter-mcp&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJnaXQraHR0cHM6Ly9naXRodWIuY29tL2FyYWE0Ny9qdXBpdGVyLW1jcCIsImp1cGl0ZXItbWNwIl0sImVudiI6eyJQUklWQVRFX0tFWSI6IlJFUExBQ0VfVEhJUyIsIlNPTEFOQV9SUENfVVJMIjoiaHR0cHM6Ly9hcGkubWFpbm5ldC1iZXRhLnNvbGFuYS5jb20iLCJTT0xBTkFfTkVUV09SSyI6Im1haW5uZXQtYmV0YSIsIlJFUVVFU1RfVElNRU9VVCI6IjMwIn19
50```
51**Note:** These links only work in Cursor
52 
53**Manual config for .env file approach:**
54 
55```json
56{
57  "mcpServers": {
58    "jupiter-mcp": {
59      "command": "npx",
60      "args": [
61        "envmcp",
62        "--env-file",
63        "/path/to/your/.env",
64        "uvx",
65        "--from",
66        "git+https://github.com/araa47/jupiter-mcp",
67        "jupiter-mcp"
68      ]
69    }
70  }
71}
72```
73 
74Replace `/path/to/your/.env` with your actual env file path (e.g., `/Users/yourname/.env`)
75 
76**Pre-configured values:**
77 
78* `SOLANA_RPC_URL`: <https://api.mainnet-beta.solana.com>
79* `SOLANA_NETWORK`: mainnet-beta
80* `REQUEST_TIMEOUT`: 30 seconds
81* `PRIVATE_KEY`: You'll need to replace `REPLACE_THIS` with your base58 encoded private key
82 
83## ⚡ Quick Start (MCP Configuration)
84 
85Add this to your MCP client configuration:
86 
87```json
88{
89  "mcpServers": {
90    "jupiter-mcp": {
91      "command": "uvx",
92      "args": [
93        "--from",
94        "git+https://github.com/araa47/jupiter-mcp",
95        "jupiter-mcp"
96      ],
97      "env": {
98        "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com",
99        "PRIVATE_KEY": "${PRIVATE_KEY}",
100        "SOLANA_NETWORK": "mainnet-beta",
101        "REQUEST_TIMEOUT": "30"
102      }
103    }
104  }
105}
106```
107 
108### Alternative Configuration (Using .env file)
109 
110If you prefer to load environment variables from a `.env` file to avoid storing sensitive data in your MCP configuration:
111 
112```json
113{
114  "mcpServers": {
115    "jupiter-mcp": {
116      "command": "npx",
117      "args": [
118        "envmcp",
119        "--env-file",
120        "${ENV_FILE_PATH}",
121        "uvx",
122        "--from",
123        "git+https://github.com/araa47/jupiter-mcp",
124        "jupiter-mcp"
125      ],
126      "env": {
127        "ENV_FILE_PATH": ".env"
128      }
129    }
130  }
131}
132```
133 
134This 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`).
135 
136### Environment Variables Required:
137 
138* `PRIVATE_KEY`: Your base58 encoded Solana private key (from Phantom wallet export)
139* Optional: Override `SOLANA_RPC_URL` if you have a custom RPC endpoint
140 
141## 🎉 Available Tools
142 
143### 💱 Ultra API (Immediate Swaps)
144 
145| Tool                       | Description                               | Parameters                        | Cost     |
146| -------------------------- | ----------------------------------------- | --------------------------------- | -------- |
147| get\_swap\_quote           | Get a swap quote and unsigned transaction | input\_mint, output\_mint, amount | **FREE** |
148| execute\_swap\_transaction | Execute a signed swap transaction         | transaction, request\_id          | **PAID** |
149| get\_balances              | Get token balances for a wallet           | wallet\_address?                  | **FREE** |
150| get\_shield                | Get token security information            | mints                             | **FREE** |
151| search\_token              | Search for tokens                         | query                             | **FREE** |
152 
153### 📊 Trigger API (Limit Orders)
154 
155| Tool                  | Description                        | Parameters                                                                              | Cost     |
156| --------------------- | ---------------------------------- | --------------------------------------------------------------------------------------- | -------- |
157| create\_limit\_order  | Create a limit order transaction   | input\_mint, output\_mint, making\_amount, taking\_amount, slippage\_bps?, expired\_at? | **FREE** |
158| execute\_limit\_order | Execute a limit order transaction  | transaction, request\_id                                                                | **PAID** |
159| cancel\_limit\_order  | Cancel a single limit order        | order                                                                                   | **FREE** |
160| cancel\_limit\_orders | Cancel multiple limit orders       | orders?                                                                                 | **FREE** |
161| get\_limit\_orders    | Get active/historical limit orders | order\_status, wallet\_address?, input\_mint?, output\_mint?, page?                     | **FREE** |
162 
163### Key Differences: Swaps vs Limit Orders
164 
165* **Swaps** (Ultra API): Execute immediately at current market price
166* **Limit Orders** (Trigger API): Execute automatically when your target price is reached
167 
168## 🛠️ Development & CI/CD
169 
170### Automated DXT Building
171 
172This project includes automated DXT building integrated with pre-commit hooks:
173 
174- **Pre-commit Hook**: Automatically builds DXT files when changes are made to `dxt/` folder
175- **Simple Naming**: Always creates `jupiter-mcp-latest.dxt` for easy downloads
176- **Auto-update**: The latest DXT file is always current with the main branch
177 
178### Manual DXT Build
179 
180```bash
181# Build DXT
182./scripts/build-dxt.sh
183 
184# Output: jupiter-mcp-latest.dxt
185```
186 
187### Pre-commit Setup
188 
189```bash
190# Install pre-commit hooks (includes DXT building)
191pre-commit install
192 
193# The DXT will be automatically built when changes are detected in:
194# - dxt/ directory
195# - scripts/build-dxt.sh
196```
197 
198## 🔧 Alternative Installation (Development)
199 
200For local development or testing:
201 
202### Prerequisites
203 
204* Python 3.12+
205* uv for dependency management
206* direnv
207 
208### Setup
209 
210```bash
211git clone https://github.com/araa47/jupiter-mcp
212cd jupiter-mcp
213direnv allow
214cp .env.example .env
215# Edit .env with your configuration
216```
217 
218### Environment Variables (.env file)
219 
220```bash
221SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
222PRIVATE_KEY=your_base58_encoded_private_key_here
223SOLANA_NETWORK=mainnet-beta
224REQUEST_TIMEOUT=30
225```
226 
227### Local Development Usage
228 
229```bash
230# Start the server locally
231uv run python run_server.py
232```
233 
234## 🧪 Testing
235 
236The project includes comprehensive testing with safety features:
237 
238### Test Types
239 
240**🆓 Free Tests** (Default - No SOL spent):
241 
242* Mock execution tests
243* API quote/balance checks
244* Token searches and security checks
245* Error handling validation
246 
247**💰 Paid Tests** (Requires `--run-paid-tests` flag):
248 
249* Real trade execution on mainnet
250* Swap tests: Uses tiny amounts (0.0001 SOL ≈ $0.015)
251* Limit order tests: Creates orders 20% above market price
252   * Uses 0.04 SOL (≈ $6) to meet minimum requirements
253   * Orders won't execute at the high price
254   * Automatically cancelled after verification
255* Full transaction signing and broadcasting
256 
257### Running Tests
258 
259```bash
260# Safe tests only (default)
261uv run pytest tests/ -v
262 
263# Include real trade execution (spends tiny amounts)
264uv run pytest tests/ -v --run-paid-tests
265 
266# Test with detailed output
267uv run pytest tests/ -v --run-paid-tests -s
268```
269 
270### Test Safety Features
271 
272* **Paid tests clearly marked** with `@pytest.mark.paid`
273* **Minimal trade amounts** for real execution
274* **Limit orders use out-of-range prices** that won't execute
275* **Clear warnings** before spending real money
276* **Transaction confirmations** with blockchain signatures
277 
278## 💡 Important Notes
279 
280### Free vs Paid Operations
281 
282* **🆓 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
283* **💰 PAID**: `execute_swap_transaction`, `execute_limit_order` - Executes real trades and spends SOL
284 
285### Automatic Referral System
286 
287* All orders include a 255 basis point (2.55%) referral fee (maximum allowed)
288* Referral wallet: `8cK8hCyRQCp52nVuPLnLL71afkRvRcFibSwHMjGFT8bm` ([Referral Dashboard](https://referral.jup.ag/dashboard/8cK8hCyRQCp52nVuPLnLL71afkRvRcFibSwHMjGFT8bm))
289* **Note**: Fees only collected for tokens with referral token accounts (currently SOL)
290* Supports development and maintenance
291 
292### Security
293 
294* 🔐 Private keys never leave your machine
295* 🛡️ All API calls use HTTPS
296* ⚠️ Never commit `.env` files to version control
297 
298## 🐛 Troubleshooting
299 
300### Common Issues
301 
3021. **"PRIVATE\_KEY environment variable is required"**
303   * Copy `env.example` to `.env` and set your private key
3042. **"Invalid PRIVATE\_KEY format"**
305   * Use base58 encoded private key (from Phantom wallet export)
3063. **Connection timeouts**
307   * Try different RPC URL or increase `REQUEST_TIMEOUT`
308 
309## 🎉 Ready to Trade!
310 
311Your Jupiter MCP server is ready for Solana DeFi interactions! 🚀
312