Paradex Py MCP Server

MCP Paradex Server

Model Context Protocol (MCP) server implementation for the Paradex trading platform.

Quickstart

New here? See the Quickstart Guide for step-by-step setup instructions for Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Claude.ai web, and ChatGPT.

Need a remote HTTP endpoint for ChatGPT or Claude.ai web? See the HTTP Deployment Guide for Railway, Render, Fly.io, AWS Lambda, and Docker/VPS options.

Overview

This project provides a bridge between AI assistants (like Claude) and Paradex, a privacy-preserving multi-asset exchange on Starknet with spot, perpetuals, options, and commodity futures. Using the MCP standard, AI assistants can:

• Retrieve market data from Paradex
• Manage trading accounts and vaults
• Place and manage orders
• Monitor positions and balance

Prerequisites

• Python 3.10+

• uv — required for the uvx run method

  macOS: Install via brew install uv so the binary lands in /usr/local/bin, which GUI apps like Claude Desktop can find. The curl-pipe install puts uv in ~/.local/bin, which GUI apps cannot see.

Installation

Quick Start

Cursor IDE

Click to automatically configure this MCP server in Cursor:

Claude Code CLI

claude mcp add paradex uvx mcp-paradex

Smithery (Claude Desktop)

npx -y @smithery/cli@latest mcp add @tradeparadex/mcp-paradex-py --client claude

Standard Installation

PyPI

pip install mcp-paradex

uvx (Recommended)

uvx mcp-paradex

Development Setup

1. Clone the repository:

   git clone https://github.com/tradeparadex/mcp-paradex-py.git
   cd mcp-paradex-py
   

2. Install development dependencies:

   uv sync --dev --all-extras
   

3. Run locally:

   uv run mcp-paradex
   

Configuration

Environment Variables

Set these environment variables for authentication:

• PARADEX_ENVIRONMENT: Set to prod, testnet, or nightly (default: prod)
• PARADEX_ACCOUNT_PRIVATE_KEY: Your Paradex account private key

Using .env File

cp .env.template .env
# Edit .env with your credentials

Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "paradex": {
      "command": "uvx",
      "args": ["mcp-paradex"],
      "env": {
        "PARADEX_ENVIRONMENT": "testnet",
        "PARADEX_ACCOUNT_PRIVATE_KEY": "your_private_key"
      }
    }
  }
}

Docker (local / stdio)

# Build image
docker build . -t tradeparadex/mcp-paradex-py

# Run (public only)
docker run --rm -i tradeparadex/mcp-paradex-py

# Run with trading capabilities
docker run --rm -e PARADEX_ACCOUNT_PRIVATE_KEY=your_key -i tradeparadex/mcp-paradex-py

Docker (AWS Lambda / HTTP)

Use Dockerfile.aws for remote deployments via AWS Lambda with the Lambda Web Adapter. The adapter bridges Lambda invocations to the server's HTTP endpoint, so no Lambda-specific code is needed.

# Build
docker build -f Dockerfile.aws -t tradeparadex/mcp-paradex-py-aws .

# Test locally (mirrors Lambda config)
docker run --rm -p 8080:8080 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_STATELESS=true \
  -e MCP_PORT=8080 \
  -e PARADEX_ENVIRONMENT=prod \
  tradeparadex/mcp-paradex-py-aws

The server will be available at http://localhost:8080/mcp.

Deploying to Lambda:

1. Push the image to ECR
2. Create a Lambda function from the container image
3. Set the Lambda Function URL invoke mode to RESPONSE_STREAM
4. Set environment variables on the Lambda function:
   • MCP_TRANSPORT=streamable-http
   • MCP_STATELESS=true
   • PARADEX_ENVIRONMENT=prod (or testnet)
   • PARADEX_ACCOUNT_PRIVATE_KEY=your_key (optional, for trading)

Available Resources and Tools

Resources

System Resources

• paradex://system/config - Get Paradex system configuration
• paradex://system/time - Get current system time
• paradex://system/state - Get system operational state

Market Resources

• paradex://markets - List of available markets
• paradex://market/summary/{market_id} - Detailed market information

Vault Resources

• paradex://vaults - List all vaults
• paradex://vaults/config - Global vault configuration
• paradex://vaults/balance/{vault_id} - Vault balance
• paradex://vaults/summary/{vault_id} - Comprehensive vault summary
• paradex://vaults/transfers/{vault_id} - Deposit/withdrawal history
• paradex://vaults/positions/{vault_id} - Current trading positions
• paradex://vaults/account-summary/{vault_id} - Trading account information

Tools

System Tools

• paradex_system_config - Get global system configuration
• paradex_system_state - Get current system state

Market Tools

• paradex_markets - Get detailed market information
• paradex_market_summaries - Get market summaries with metrics
• paradex_funding_data - Get historical funding rate data
• paradex_orderbook - Get current orderbook with customizable depth
• paradex_klines - Get historical candlestick data
• paradex_trades - Get recent trades
• paradex_bbo - Get best bid and offer

Account Tools

• paradex_account_summary - Get account summary
• paradex_account_positions - Get current positions
• paradex_account_fills - Get trade fills
• paradex_account_funding_payments - Get funding payments
• paradex_account_transactions - Get transaction history

Order Tools

• paradex_open_orders - Get all open orders
• paradex_create_order - Create new order
• paradex_cancel_orders - Cancel existing orders
• paradex_order_status - Get order status
• paradex_orders_history - Get historical orders

Vault Tools

• paradex_vaults - Get detailed vault information
• paradex_vaults_config - Get global vault configuration
• paradex_vault_balance - Get vault balance
• paradex_vault_summary - Get comprehensive vault summary
• paradex_vault_transfers - Get deposit/withdrawal history
• paradex_vault_positions - Get current vault positions
• paradex_vault_account_summary - Get vault trading account info

Trading Analysis Prompts

Market Analysis

• market_overview - Comprehensive crypto market overview
• market_analysis - Detailed technical and microstructure analysis

Position and Portfolio Management

• position_management - Comprehensive position analysis
• create_optimal_order - Design optimal order parameters
• hedging_strategy - Develop effective hedging strategies
• portfolio_risk_assessment - Thorough portfolio risk analysis
• liquidation_protection - Identify and mitigate liquidation risks

Investment Strategies

• vault_analysis - Comprehensive vault analysis for investment decisions
• funding_rate_opportunity - Identify funding rate arbitrage opportunities
• trading_consultation - Interactive trading advice and consultation

Documentation MCP

Enhanced results with Paradex documentation access:

"paradex-docs-mcp": {
   "command": "uvx",
   "args": [
      "--from",
      "mcpdoc",
      "mcpdoc",
      "--urls",
      "Paradex:https://docs.paradex.trade/llms.txt",
      "--transport",
      "stdio"
   ]
}

Contributing

Please see CONTRIBUTING.md for information on how to contribute to this project, development setup, and our coding standards.

License

MIT License