AEVO MCP

Agentic Trading on Aevo

The Aevo MCP Server enables AI agents to connect directly to the Aevo exchange through the Model Context Protocol (MCP). It allows any MCP-compatible client, such as Claude Code, Claude Desktop, Cursor, Windsurf, or OpenClaw, to retrieve market data, manage accounts, and execute trades on Aevo using natural language.

The server is open-source and available on GitHub:

• aevo-mcp - The MCP server itself

• aevo-trading-skills - AI skill definitions for trading workflows

---

Capabilities

The Aevo MCP Server exposes 45+ tools across five categories:

• Market Analysis: Real-time prices, funding rates, volatility snapshots, and market regime classification.

• Portfolio Management: Positions, risk metrics, Greeks, and margin monitoring.

• Order Execution: Limit orders, bracket orders (entry + stop-loss + take-profit), and batch operations.

• Options Strategies: Straddles, strangles, spreads, iron condors, and butterflies with live pricing.

• Risk Management: Pre-trade validation, portfolio risk scoring, and liquidation distance monitoring.

In addition to tools, the server provides built-in Prompts (such as trade_plan, risk_checklist, cancel_plan, and onboarding_plan) and Resources (such as aevo://status, aevo://markets/summary, and aevo://account/overview) for structured agent workflows.

---

Getting Your Credentials

1. Navigate to app.aevo.xyz/settings.

2. Create an API key. This gives you an api_key and api_secret.

3. For trading, you also need your wallet_address and signing_key_private_key.

Credential Tiers

Tier	Credentials Required	Access Level
Read-only	api_key + api_secret	Account data, positions, trade history
Trading	+ wallet_address + signing_key_private_key	Orders, cancellations, strategies

If you do not yet have API keys, you can set AEVO_WALLET_ADDRESS and AEVO_WALLET_PRIVATE_KEY as environment variables and use the register_account tool to generate them. It is recommended to create an account first and use the Aevo wallet to generate keys.

---

Connection Methods

Hosted MCP Endpoint (No Local Server)

Aevo provides a hosted MCP endpoint that requires no local installation. Point any MCP-compatible client to:

• Mainnet: https://mcp.aevo.xyz/mcp

• Testnet: https://mcp-testnet.aevo.xyz/mcp

Authenticate using AEVO-KEY and AEVO-SECRET headers, or call the aevo_authenticate tool after connecting.

Example — Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "aevo": {
      "url": "https://mcp.aevo.xyz/mcp",
      "headers": {
        "AEVO-KEY": "your-api-key",
        "AEVO-SECRET": "your-api-secret"
      }
    }
  }
}

Self-Hosted with Docker (Recommended)

Clone the repository and run the server locally via Docker:

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

Edit .env with your Aevo credentials:

AEVO_API_KEY=your_key
AEVO_API_SECRET=your_secret
AEVO_SIGNING_KEY_PRIVATE_KEY=your_signing_key

Start the server:

docker compose up --build -d

Then connect Claude Code:

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

Example — Claude Desktop config (Docker):

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

Local Install (No Docker)

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

Connect Claude Code via stdio:

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

Example — Claude Desktop config (local):

{
  "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"
      }
    }
  }
}

OpenClaw

clawhub install aevo

After installing, add your Aevo credentials as environment variables in your OpenClaw config.

---

Environment Variables

Variable	Required	Description
AEVO_API_KEY	Yes*	API key from your Aevo account settings
AEVO_API_SECRET	Yes*	API secret from your Aevo account settings
AEVO_SIGNING_KEY_PRIVATE_KEY	Yes	Signing key required for order submission
AEVO_ENVIRONMENT	No	testnet or mainnet (default: mainnet)
AEVO_WALLET_ADDRESS	No	Wallet address (used with register_account tool)
AEVO_WALLET_PRIVATE_KEY	No	Wallet private key (used with register_account tool)
AEVO_AUTO_REGISTER	No	Auto-register signing key on startup (true / false)

* Not required if using AEVO_WALLET_ADDRESS + AEVO_WALLET_PRIVATE_KEY with the register_account tool to generate API keys.

---

Verifying Your Setup

Once connected, open a new session in your MCP client and type:

call the ping tool

You should see {"ok": true, "result": {"status": "ok"}}. Then try:

check my account balance

If your credentials are configured correctly, the agent will return your current account balance and equity.

---

Testnet

For testing without real funds, use the Aevo testnet environment:

Resource	URL
Testnet App	testnet.aevo.xyz
Testnet API	https://api-testnet.aevo.xyz
Testnet MCP	https://mcp-testnet.aevo.xyz/mcp

Set AEVO_ENVIRONMENT=testnet in your environment variables when running the self-hosted server.

---

Aevo Trading Skill

The Aevo Trading Skill provides structured guidance that helps AI agents use the MCP tools effectively. It includes reference material for all 45 tools, instrument naming conventions, risk guardrails, step-by-step workflow recipes, and an options strategy reference.

The skill can be installed alongside the MCP server for clients that support skill definitions (such as Claude Code or OpenClaw), giving the agent deeper context on how to plan trades, manage risk, and execute multi-leg strategies.