keel-trade

The Keel CLI and stdio MCP server.
Build, backtest, and automate Hyperliquid trading strategies — with your agent in the loop for creation and a deterministic engine in the loop for execution.

Website · Product page · Docs · Sample backtest · Discussions

What is Keel?

Keel is a quantitative crypto trading platform built around Hyperliquid — strategy development, backtesting, live execution, and portfolio management on the venue with the deepest on-chain perpetual order book. The full platform includes:

• A web app for composing strategies, running backtests, and deploying live (app.usekeel.io)
• A deterministic backtest engine with real Hyperliquid funding + price + slippage, walk-forward, and Monte Carlo
• Bit-for-bit live execution — the same compiled strategy artifact runs in backtest and on Hyperliquid
• A strategy library of documented, forkable trading strategies
• A screener + calculator suite at usekeel.io/lab (funding leaderboard, momentum, overfit-check, walk-forward visualizer, more)
• This package — keel-trade — the agent-native research surface

This repository is the public mirror of the keel-trade Python package: a single pipx install gives you both a CLI and a stdio MCP server, so the same tools work from a terminal or from any MCP-capable agent.

Why agents create strategies, not trade them

Most agent-trading projects put an LLM in the execution loop. That makes systems slow, inconsistent, and hard to audit. Keel does the opposite:

You ──── compose ────► Strategy graph ──── compile ────► Deterministic artifact
                              ▲                                    │
                              │                                    ▼
                          Agent edits                          Backtest engine
                          via MCP tools                        (real HL data)
                                                                   │
                                                                   ▼
                                                              Live execution
                                                              (same artifact)

Three properties drive the design:

1. Bit-for-bit parity between backtest and live. Same compiled artifact, same engine, same data path. There is no second implementation that can drift.
2. Typed composition over freeform code. Strategies are graphs of versioned components. Compile errors catch bugs at author time instead of in production.
3. Agents compose, the deterministic engine executes. Claude / Cursor / Codex help you build the strategy. They are not in the trade loop.

Install

Claude Desktop — one-click (MCPB)

Download keel-trade-<version>.mcpb from the latest release and drag onto Claude Desktop. Cross-platform single bundle — works on macOS, Windows, and Linux.

The MCPB bundle requires system Python 3.11+ (same prerequisite as the terminal install path below). First launch takes ~10-30 seconds while the bundle pip-installs runtime deps to ~/.keel/mcpb-lib/py3.X/; subsequent launches are instant.

Terminal — pipx / uv (Claude Code, Codex, Cursor, Windsurf, etc.)

pipx install keel-trade

uv tool install keel-trade also works. Python 3.11+.

Then register the stdio MCP command with your agent host:

# Claude Code
claude mcp add keel -- keel mcp serve

# Codex
codex mcp add keel -- keel mcp serve

For Cursor, Windsurf, and generic MCP clients, see usekeel.io/keel-mcp#install or the agent setup guide.

First conversation with your agent

After install, sign in once via the agent (no terminal commands needed):

You: "Connect to Keel."

Agent: Calls keel_auth_login. Browser opens to app.usekeel.io, you click Allow, tokens land in ~/.keel/config.yaml. Authenticated for 30 days with transparent refresh.

Then describe what you want:

You: "Find me momentum signals for Hyperliquid top-30 perps and compose a backtest from 2024-08-15 to today."

Agent: Calls keel_components_search → keel_components_detail_batch → keel_strategy_compose → keel_backtest_run. Returns a share URL with the full tearsheet (equity curve, Sharpe, max drawdown, per-asset attribution).

Concrete example: this share URL is a funding-carry backtest produced through exactly this flow — Sharpe 2.17 over 2024-08-15 → 2026-04-30 on real Hyperliquid data.

What the MCP exposes

The default toolset spans status, auth, components, strategy lifecycle, backtest, audit, accounts, sharing, and read-only live monitoring. Live-write tools (keel_live_deploy, keel_live_control) require an explicit opt-in toolset plus a local arming step — agents can't deploy your account without you authorizing it twice.

Full per-tool reference: usekeel.io/docs/sdk/tool-reference.

CLI usage

Every MCP outcome tool has a CLI mirror. Useful for terminals, SSH sessions, CI, scripts, or agents that prefer subprocess calls:

# Auth + status
keel auth login
keel status

# Search components, compose, backtest
keel components search "momentum"
keel strategy compose --source-file my-strategy.py --dry-run
keel backtest run str_abc123 --start-date 2024-08-15 --wait

# Inspect a strategy
keel strategy get str_abc123
keel strategy log str_abc123

Full CLI reference: usekeel.io/docs/sdk/cli-reference.

What you can do with Keel

Documentation

• Product page: usekeel.io/keel-mcp
• Getting started: usekeel.io/docs/getting-started
• Agent setup (per host): usekeel.io/docs/sdk/agent-setup
• CLI reference: usekeel.io/docs/sdk/cli-reference
• MCP tool reference: usekeel.io/docs/sdk/tool-reference
• REST API reference: usekeel.io/docs/api-reference
• Agent instructions (canonical, machine-readable): AGENTS.md

Status

Alpha. The CLI and MCP surface are stable and ship to PyPI on a regular cadence; the underlying engine and component library are actively developed.

How to contribute / report a bug

See CONTRIBUTING.md. Short version:

• Bug report → open an issue using the bug template
• Feature request, question, or pattern share → use Discussions
• Security issue → email team@usekeel.io (do not open a public issue)
• Patches → PRs are welcome; we maintain in a private monorepo so PRs may take longer to land — see CONTRIBUTING for the porting process

Related

• Keel on Hyperliquid — the platform
• What is MCP?
• AI agents on Hyperliquid — the definitive guide
• Why we don't put LLMs in the trade loop

License

MIT. See LICENSE.

Built by the Keel Research Team · @usekeelio