mcp-paradex-py: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP Paradex Server is a Model Context Protocol (MCP) server implementation for the Paradex perpetual futures trading platform. It provides a bridge between AI assistants (like Claude) and the Paradex platform, allowing the assistants to retrieve market data, manage trading accounts and vaults, place and manage orders, and monitor positions and balances.

Commands

Environment Setup

# Create and activate a virtual environment with uv (recommended)
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -e .

# Install development dependencies
make install-dev
# OR
pip install -e ".[dev]"
pre-commit install

Development Commands

# Format code with ruff
make format
# OR
ruff format src tests

# Lint code with ruff
make lint
# OR
ruff check src tests --fix

# Type check with ty
make typecheck
# OR
ty check src

# Run tests
make test
# OR
pytest

# Run tests with coverage report
make test-cov
# OR
pytest --cov=mcp_paradex --cov-report=html

# Run all checks (format, lint, typecheck, test)
make check

# Run pre-commit hooks on all files
make pre-commit
# OR
pre-commit run --all-files

# Clean up cache files
make clean

Running the Server

# Run the server using the CLI
python -m mcp_paradex

# Build and run with Docker
docker build . -t sv/mcp-paradex-py
docker run --rm -i sv/mcp-paradex-py  # Public only
docker run --rm -e PARADEX_ACCOUNT_PRIVATE_KEY=0xprivatekey -i sv/mcp-paradex-py  # Allow trading

Architecture

The MCP Paradex Server is structured as follows:

• Server: The core server component using FastMCP to handle MCP protocol requests
• Resources: Read-only data endpoints structured as URIs
  • System resources: Configuration, time, state
  • Market resources: Lists of markets, market summaries
  • Vault resources: Lists of vaults, vault configurations, balances
• Tools: Action-based tools exposed to AI assistants
  • System tools: Configuration, state management
  • Market tools: Market data, order books, trades, etc.
  • Account tools: Balance, positions, transaction history
  • Order tools: Create/cancel orders, monitor order status
  • Vault tools: Balance, transfers, positions
• Prompts: Structured prompts for trading analysis and strategy generation
  • Market analysis and trading recommendations
  • Position and portfolio management
  • Investment strategies