Keel

[keel-trade — Build, backtest, and automate Hyperliquid trading strategies with your agent]

keel-trade

The Keel CLI and stdio MCP server.
Build and backtest Hyperliquid perpetual-futures strategies with your AI assistant — typed strategy composition and deterministic backtests on real Hyperliquid market history. Running a strategy with real capital happens in the Keel web app.

[PyPI version] [Python 3.11+] [MIT License] [Product page] [keel-trade MCP server]

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 and slippage
• 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.

Quick start — the hosted MCP, nothing to install

Paste one URL into the client you already use. You sign in through your client's own OAuth flow; no API key to copy, no local install.

Hosted endpoint URL: https://mcp.usekeel.io/mcp — one endpoint, a 29-tool research/backtest/read surface, nothing to install. Sign in or sign up on the Keel page that opens (no account needed beforehand); authentication is your MCP client's OAuth flow, never a tool call.

• Claude: Customize → Connectors → Add custom connector. Paste https://mcp.usekeel.io/mcp and choose Connect.
• ChatGPT: Settings → Security and login → turn on Developer mode (a paid ChatGPT plan; on Business/Enterprise an admin must allow it). Open chatgpt.com/plugins, choose +, give the connector a name and a description, and enter https://mcp.usekeel.io/mcp as the MCP server URL (the /mcp path included).
• Claude Code: claude mcp add --transport http keel https://mcp.usekeel.io/mcp. Inside Claude Code run /mcp and choose Authenticate.
• Cursor: Add the server to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global): {"mcpServers": {"keel": {"url": "https://mcp.usekeel.io/mcp"}}}. Cursor asks you to sign in on first use.
• Codex: codex mcp add keel --url https://mcp.usekeel.io/mcp then codex mcp login keel. Codex opens your browser for the sign-in.
• Windsurf: Add the server to Windsurf's mcp_config.json: {"mcpServers": {"keel": {"serverUrl": "https://mcp.usekeel.io/mcp"}}}. Windsurf asks you to sign in on first use.
• VS Code: Add the server to .vscode/mcp.json, or open the install link: {"servers": {"keel": {"type": "http", "url": "https://mcp.usekeel.io/mcp"}}}. VS Code asks you to sign in on first use.
• Other: Use your client's own add remote / HTTP MCP server flow with https://mcp.usekeel.io/mcp. The first request answers 401 with OAuth 2.1 metadata, so a compliant client discovers the sign-in step by itself.

The agent builds, tests and reads. When you want to run a strategy on your account, it hands it to the Keel app and you take it from there.

Setup guide: https://usekeel.io/docs/agents/setup · Per-client runbook: https://usekeel.io/agents

No Keel account yet? Create one free — then connect the endpoint above and ask your agent to build something.

Choose your surface

Keel is one product with several places to use it. The hosted MCP above is the default; this package is the CLI + local MCP path.

• CLI + local MCP — this package (install below).
• SDK + API key — the REST API for building your own agents and scripts.

Per-surface zero-to-first-backtest runbook: usekeel.io/agents.

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.

The bundle runs this package's local MCP server: your assistant composes and validates strategies, backtests them on real Hyperliquid history, browses the strategy library, compares runs, and shares results. Sign in once with keel_auth_login. By default it cannot place orders or move funds — running a strategy with real capital happens in the Keel web app, and the local tools that act on a live account stay off unless you enable them and arm them on your machine (details below). Prefer nothing to install? Claude Desktop also works with the hosted connector in the quick start.

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 Codeclaude mcp add keel -- keel mcp serve
# Codexcodex 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_get_many → 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 local toolsets (always, read-only, backtest, share, live-read) span status, auth, components, strategy lifecycle, backtest, audit, accounts, sharing, and read-only live monitoring.

Live-write tools (keel_live_deploy, keel_live_control, keel_live_update) are off unless you opt in with KEEL_TOOLSETS. Even then, going live is a hand-off: keel_live_deploy places no orders and returns a link into the Keel web app, where you choose the account, review sizing, and start the strategy. Acting on a live account from your machine (keel_live_control, or the operator-only direct deploy) also requires local arming (keel arm live set). The hosted connector at mcp.usekeel.io has no live-write tools at all.

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 + statuskeel auth login                      # opens a browserkeel auth login --key "$KEEL_API_KEY"  # CI / SSH / no browserkeel status
# Search components, compose, backtestkeel components search "momentum"keel strategy compose --source-file my-strategy.py --dry-runkeel backtest run str_abc123 --start-date 2024-08-15 --wait
# Inspect a strategykeel strategy get str_abc123keel 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/agents/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.

Keel measures the strategies you design. It is not investment advice, and backtest results do not predict future returns.

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 [email protected] (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