Perp Cli

by hypurrquant

1.1k downloads Not rated yet

GitHub

About

MCP server for perpetual futures trading across Pacifica (Solana), Hyperliquid (HyperEVM), and Lighter (Ethereum). 18 tools for market data, portfolio management, trade execution with dry-run safety, funding rate arbitrage scanning, and analytics.

Explore

- 3 Exchanges — trade, bridge, arbitrage across Pacifica, Hyperliquid, Lighter
- Funding Rate Arb — perp-perp + spot-perp scan & one-command dual-leg execution
- Portfolio — single call returns balances, positions, risk level across all exchanges
- Funds — deposit, withdraw, CCTP bridge, internal transfer in one group
- Bots — TWAP, grid, DCA, trailing-stop with background job management
- Agent-First Design — --json, --fields, --ndjson, --dry-run, runtime schema introspection
- Safety — pre-trade validation, response sanitization, client-id deduplication

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Perp Cli

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "perp cli": {
            "perp-cli": {
                "command": "npx",
                "args": [
                    "-y",
                    "-p",
                    "perp-cli",
                    "perp-mcp"
                ],
                "env": {
                    "HYPERLIQUID_PRIVATE_KEY": "<YOUR_EVM_KEY>",
                    "PACIFICA_PRIVATE_KEY": "<YOUR_SOLANA_KEY>",
                    "LIGHTER_PRIVATE_KEY": "<YOUR_EVM_KEY>"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "perp cli": {
            "perp-cli": {
                "command": "npx",
                "args": [
                    "-y",
                    "-p",
                    "perp-cli",
                    "perp-mcp"
                ],
                "env": {
                    "HYPERLIQUID_PRIVATE_KEY": "<YOUR_EVM_KEY>",
                    "PACIFICA_PRIVATE_KEY": "<YOUR_SOLANA_KEY>",
                    "LIGHTER_PRIVATE_KEY": "<YOUR_EVM_KEY>"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "perp cli": {
            "perp-cli": {
                "command": "npx",
                "args": [
                    "-y",
                    "-p",
                    "perp-cli",
                    "perp-mcp"
                ],
                "env": {
                    "HYPERLIQUID_PRIVATE_KEY": "<YOUR_EVM_KEY>",
                    "PACIFICA_PRIVATE_KEY": "<YOUR_SOLANA_KEY>",
                    "LIGHTER_PRIVATE_KEY": "<YOUR_EVM_KEY>"
                }
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "perp cli": {
            "perp-cli": {
                "command": "npx",
                "args": [
                    "-y",
                    "-p",
                    "perp-cli",
                    "perp-mcp"
                ],
                "env": {
                    "HYPERLIQUID_PRIVATE_KEY": "<YOUR_EVM_KEY>",
                    "PACIFICA_PRIVATE_KEY": "<YOUR_SOLANA_KEY>",
                    "LIGHTER_PRIVATE_KEY": "<YOUR_EVM_KEY>"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "perp cli": {
            "perp-cli": {
                "command": "npx",
                "args": [
                    "-y",
                    "-p",
                    "perp-cli",
                    "perp-mcp"
                ],
                "env": {
                    "HYPERLIQUID_PRIVATE_KEY": "<YOUR_EVM_KEY>",
                    "PACIFICA_PRIVATE_KEY": "<YOUR_SOLANA_KEY>",
                    "LIGHTER_PRIVATE_KEY": "<YOUR_EVM_KEY>"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "perp cli": {
            "perp-cli": {
                "command": "npx",
                "args": [
                    "-y",
                    "-p",
                    "perp-cli",
                    "perp-mcp"
                ],
                "env": {
                    "HYPERLIQUID_PRIVATE_KEY": "<YOUR_EVM_KEY>",
                    "PACIFICA_PRIVATE_KEY": "<YOUR_SOLANA_KEY>",
                    "LIGHTER_PRIVATE_KEY": "<YOUR_EVM_KEY>"
                }
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "perp cli": {
            "perp-cli": {
                "command": "npx",
                "args": [
                    "-y",
                    "-p",
                    "perp-cli",
                    "perp-mcp"
                ],
                "env": {
                    "HYPERLIQUID_PRIVATE_KEY": "<YOUR_EVM_KEY>",
                    "PACIFICA_PRIVATE_KEY": "<YOUR_SOLANA_KEY>",
                    "LIGHTER_PRIVATE_KEY": "<YOUR_EVM_KEY>"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "perp cli": {
            "perp-cli": {
                "command": "npx",
                "args": [
                    "-y",
                    "-p",
                    "perp-cli",
                    "perp-mcp"
                ],
                "env": {
                    "HYPERLIQUID_PRIVATE_KEY": "<YOUR_EVM_KEY>",
                    "PACIFICA_PRIVATE_KEY": "<YOUR_SOLANA_KEY>",
                    "LIGHTER_PRIVATE_KEY": "<YOUR_EVM_KEY>"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "perp cli": {
            "perp-cli": {
                "command": "npx",
                "args": [
                    "-y",
                    "-p",
                    "perp-cli",
                    "perp-mcp"
                ],
                "env": {
                    "HYPERLIQUID_PRIVATE_KEY": "<YOUR_EVM_KEY>",
                    "PACIFICA_PRIVATE_KEY": "<YOUR_SOLANA_KEY>",
                    "LIGHTER_PRIVATE_KEY": "<YOUR_EVM_KEY>"
                }
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "perp cli": {
            "perp-cli": {
                "command": "npx",
                "args": [
                    "-y",
                    "-p",
                    "perp-cli",
                    "perp-mcp"
                ],
                "env": {
                    "HYPERLIQUID_PRIVATE_KEY": "<YOUR_EVM_KEY>",
                    "PACIFICA_PRIVATE_KEY": "<YOUR_SOLANA_KEY>",
                    "LIGHTER_PRIVATE_KEY": "<YOUR_EVM_KEY>"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "perp cli": {
            "perp-cli": {
                "command": "npx",
                "args": [
                    "-y",
                    "-p",
                    "perp-cli",
                    "perp-mcp"
                ],
                "env": {
                    "HYPERLIQUID_PRIVATE_KEY": "<YOUR_EVM_KEY>",
                    "PACIFICA_PRIVATE_KEY": "<YOUR_SOLANA_KEY>",
                    "LIGHTER_PRIVATE_KEY": "<YOUR_EVM_KEY>"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "perp cli": {
            "perp-cli": {
                "command": "npx",
                "args": [
                    "-y",
                    "-p",
                    "perp-cli",
                    "perp-mcp"
                ],
                "env": {
                    "HYPERLIQUID_PRIVATE_KEY": "<YOUR_EVM_KEY>",
                    "PACIFICA_PRIVATE_KEY": "<YOUR_SOLANA_KEY>",
                    "LIGHTER_PRIVATE_KEY": "<YOUR_EVM_KEY>"
                }
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "perp cli": {
            "perp-cli": {
                "command": "npx",
                "args": [
                    "-y",
                    "-p",
                    "perp-cli",
                    "perp-mcp"
                ],
                "env": {
                    "HYPERLIQUID_PRIVATE_KEY": "<YOUR_EVM_KEY>",
                    "PACIFICA_PRIVATE_KEY": "<YOUR_SOLANA_KEY>",
                    "LIGHTER_PRIVATE_KEY": "<YOUR_EVM_KEY>"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "perp cli": {
            "perp-cli": {
                "command": "npx",
                "args": [
                    "-y",
                    "-p",
                    "perp-cli",
                    "perp-mcp"
                ],
                "env": {
                    "HYPERLIQUID_PRIVATE_KEY": "<YOUR_EVM_KEY>",
                    "PACIFICA_PRIVATE_KEY": "<YOUR_SOLANA_KEY>",
                    "LIGHTER_PRIVATE_KEY": "<YOUR_EVM_KEY>"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "perp cli": {
            "perp-cli": {
                "command": "npx",
                "args": [
                    "-y",
                    "-p",
                    "perp-cli",
                    "perp-mcp"
                ],
                "env": {
                    "HYPERLIQUID_PRIVATE_KEY": "<YOUR_EVM_KEY>",
                    "PACIFICA_PRIVATE_KEY": "<YOUR_SOLANA_KEY>",
                    "LIGHTER_PRIVATE_KEY": "<YOUR_EVM_KEY>"
                }
            }
        }
    }
}

From the repository

Install globally with npm install -g perp-cli, set exchange keys using perp wallet set, then run commands such as perp --json portfolio. For MCP server use npx -y perp-cli perp-mcp in your MCP client config.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "perp cli": {
            "perp-cli": {
                "command": "npx",
                "args": [
                    "-y",
                    "-p",
                    "perp-cli",
                    "perp-mcp"
                ],
                "env": {
                    "HYPERLIQUID_PRIVATE_KEY": "<YOUR_EVM_KEY>",
                    "PACIFICA_PRIVATE_KEY": "<YOUR_SOLANA_KEY>",
                    "LIGHTER_PRIVATE_KEY": "<YOUR_EVM_KEY>"
                }
            }
        }
    }
}

McpServers

{
    "perp-cli": {
        "command": "npx",
        "args": [
            "-y",
            "-p",
            "perp-cli",
            "perp-mcp"
        ],
        "env": {
            "HYPERLIQUID_PRIVATE_KEY": "<YOUR_EVM_KEY>",
            "PACIFICA_PRIVATE_KEY": "<YOUR_SOLANA_KEY>",
            "LIGHTER_PRIVATE_KEY": "<YOUR_EVM_KEY>"
        }
    }
}