# 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)](https://modelcontextprotocol.io/). 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**](https://github.com/ribbon-finance/aevo-mcp) **-** The MCP server itself
* [**aevo-trading-skills**](https://github.com/ribbon-finance/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](https://app.aevo.xyz/settings/api-keys).
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):

```json
{
  "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:

```bash
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:

```bash
docker compose up --build -d
```

Then connect Claude Code:

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

**Example — Claude Desktop config (Docker):**

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

### Local Install (No Docker)

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

Connect Claude Code via stdio:

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

**Example — Claude Desktop config (local):**

```json
{
  "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

```bash
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](https://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](https://github.com/ribbon-finance/aevo-trading-skills) 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.