Aevo

MCP server for trading on AEVO — works with Claude Code, Claude Desktop, or any MCP client.

Quick Start (Docker + Claude Code)

1. Clone and configure

git clone https://github.com/ribbon-finance/aevo-mcp.git
cd aevo-mcp
cp .env.example .env

Edit .env with your AEVO credentials (get them from app.aevo.xyz/settings):

AEVO_API_KEY=your_key
AEVO_API_SECRET=your_secret
AEVO_SIGNING_KEY_PRIVATE_KEY=your_signing_key

2. Start the server

docker compose up --build -d

3. Connect Claude Code

claude mcp add --transport http aevo-trading http://localhost:8080/mcp

4. Test it

Open a new Claude Code session and type:

call the ping tool

You should see {"ok": true, "result": {"status": "ok"}}. Try check my account balance to verify your credentials work.

Alternative Setup

Local (no Docker)

pip install -e .
cp .env.example .env   # edit with your credentials
aevo-mcp --transport stdio

Then connect Claude Code via stdio:

claude mcp add --transport stdio aevo-trading -- aevo-mcp --transport stdio

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

With Docker (recommended):

{
  "mcpServers": {
    "aevo-trading": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

With local install:

{
  "mcpServers": {
    "aevo-trading": {
      "command": "aevo-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "AEVO_API_KEY": "your_key",
        "AEVO_API_SECRET": "your_secret",
        "AEVO_SIGNING_KEY_PRIVATE_KEY": "your_signing_key"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
AEVO_API_KEY	Yes*	API key
AEVO_API_SECRET	Yes*	API secret
AEVO_SIGNING_KEY_PRIVATE_KEY	Yes	Signing key for order submission
AEVO_ENVIRONMENT	No	testnet or mainnet (default)
AEVO_WALLET_ADDRESS	No	Wallet address (for register_account tool)
AEVO_WALLET_PRIVATE_KEY	No	Wallet private key (for register_account tool)
AEVO_AUTO_REGISTER	No	Auto-register on startup (true/false)

* Don't have API keys? Set AEVO_WALLET_ADDRESS + AEVO_WALLET_PRIVATE_KEY and use the register_account tool to generate them. Advise to have a account and use aevo wallet to generate keys.

What's Included

Tools: markets, account, portfolio, positions, orderbook, build_order, create_order, cancel_order, cancel_all, register_account, and more.

Prompts: trade_plan, risk_checklist, cancel_plan, onboarding_plan

Resources: aevo://status, aevo://markets/summary, aevo://account/overview

Tests

pip install -e ".[test]"
pytest -q tests/