# keel-trade/keel-trade [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/keel-trade/keel-trade  
**GitHub Stars:** 1  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/keel-trade-keel-trade

## Description
Build, backtest, and automate Hyperliquid trading strategies. Typed strategy composition, deterministic backtests on real Hyperliquid funding + price history, opt-in live execution with bit-for-bit backtest-to-live parity.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "keel-trade": {
    "command": "npx",
    "args": ["-y","keel-trade-keel-trade"]
  }
}
```

## Documentation & README

<p align="center">
  <a href="https://usekeel.io/keel-mcp">
    <img src="https://usekeel.io/og/keel-mcp.png" alt="keel-trade — Build, backtest, and automate Hyperliquid trading strategies with your agent" width="100%">
  </a>
</p>

<h1 align="center">keel-trade</h1>

<p align="center">
  <strong>The Keel CLI and stdio MCP server.</strong><br>
  Build, backtest, and automate <a href="https://hyperliquid.xyz">Hyperliquid</a> trading strategies — with your agent in the loop for <em>creation</em> and a deterministic engine in the loop for <em>execution</em>.
</p>

<p align="center">
  <a href="https://pypi.org/project/keel-trade/"><img src="https://img.shields.io/pypi/v/keel-trade.svg" alt="PyPI version"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+"></a>
  <a href="https://github.com/keel-trade/keel-trade/blob/HEAD/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License"></a>
  <a href="https://usekeel.io/keel-mcp"><img src="https://img.shields.io/badge/product-keel--mcp-635BFF.svg" alt="Product page"></a>
  <a href="https://glama.ai/mcp/servers/keel-trade/keel-trade"><img src="https://glama.ai/mcp/servers/keel-trade/keel-trade/badges/score.svg" alt="keel-trade MCP server"></a>
</p>

<p align="center">
  <a href="https://usekeel.io">Website</a> ·
  <a href="https://usekeel.io/keel-mcp">Product page</a> ·
  <a href="https://usekeel.io/docs">Docs</a> ·
  <a href="https://app.usekeel.io/share/gDXjURKqWPs8CZ4eXdqAI?ref=H0O2KN">Sample backtest</a> ·
  <a href="https://github.com/keel-trade/keel-trade/discussions">Discussions</a>
</p>

---

## What is Keel?

[Keel](https://usekeel.io) 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](https://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](https://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.

## Choose your surface

`keel-trade` (this package) is the CLI + local MCP path. Keel is one product
with several places to use it — pick by where you are:

<!-- surface-routing:begin -->
<!-- GENERATED from shared/surface-routing.json — edit there, then run
     python packages/keel-trade/keel-sdk/scripts/check_surface_routing.py --write -->
| You are… | Default path (shown first) | Also works |
| --- | --- | --- |
| Using Claude/ChatGPT on web or phone | Hosted endpoint — paste the URL (directory one-click coming) | CLI + local MCP |
| Working in Claude Code / Cursor / terminal | `pipx install keel-trade` (CLI + local MCP) | hosted endpoint |
| Going live with a strategy | Keel web app (connect account, review sizing, go live) | reads on every surface |
| Building your own agent/scripts | SDK + API key | CLI |
| Just browsing/running strategies | Web app + library | hosted endpoint |
<!-- surface-routing:end -->

- **Hosted endpoint** — the remote MCP at `https://mcp.usekeel.io/mcp`: one
  23-tool research/backtest/read surface (compose, backtest, share, read-only
  monitoring — no live-write, no local files). Paste the URL into any
  remote-MCP client; the one-click directory listing is coming. Going live is
  a handoff into the Keel web app.
- **CLI + local MCP** — this package (install below).
- **SDK + API key** — the [REST API](https://usekeel.io/docs/api-reference)
  for building your own agents and scripts.

Per-surface zero-to-first-backtest runbook: [usekeel.io/agents](https://usekeel.io/agents).

## Install

### Claude Desktop — one-click (MCPB)

Download `keel-trade-<version>.mcpb` from the [latest release](https://github.com/keel-trade/keel-trade/releases/latest) 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.)

```bash
pipx install keel-trade
```

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

Then register the stdio MCP command with your agent host:

```bash
# 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](https://usekeel.io/keel-mcp#install) or the [agent setup guide](https://usekeel.io/docs/sdk/agent-setup).

## 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](https://app.usekeel.io/share/gDXjURKqWPs8CZ4eXdqAI?ref=H0O2KN) 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](https://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:

```bash
# 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](https://usekeel.io/docs/sdk/cli-reference).

## What you can do with Keel

| Task                                                                           | Surface                                                                                    |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| **Backtest a Hyperliquid strategy** — real fees, funding, slippage, ~220 perps | [usekeel.io/hyperliquid-backtest](https://usekeel.io/hyperliquid-backtest)                 |
| **Screen HL perps** — momentum, funding, volume, breakout, regime              | [usekeel.io/lab](https://usekeel.io/lab)                                                   |
| **Use AI to build strategies** — typed composition, not freeform code          | [usekeel.io/ai-trading-strategy-builder](https://usekeel.io/ai-trading-strategy-builder)   |
| **Backtest portfolios** across the HL universe                                 | [usekeel.io/crypto-portfolio-backtesting](https://usekeel.io/crypto-portfolio-backtesting) |
| **Robustness diagnostics** — walk-forward, Monte Carlo, deflated Sharpe, PBO   | [usekeel.io/hyperliquid](https://usekeel.io/hyperliquid)                                   |
| **Deploy a strategy live** on Hyperliquid (non-custodial)                      | [usekeel.io/strategy-os](https://usekeel.io/strategy-os)                                   |
| **Compare strategies + venues**                                                | [usekeel.io/compare](https://usekeel.io/compare)                                           |
| **Browse documented trading strategies**                                       | [usekeel.io/strategies](https://usekeel.io/strategies)                                     |

## Documentation

- **Product page**: [usekeel.io/keel-mcp](https://usekeel.io/keel-mcp)
- **Getting started**: [usekeel.io/docs/getting-started](https://usekeel.io/docs/getting-started)
- **Agent setup (per host)**: [usekeel.io/docs/sdk/agent-setup](https://usekeel.io/docs/sdk/agent-setup)
- **CLI reference**: [usekeel.io/docs/sdk/cli-reference](https://usekeel.io/docs/sdk/cli-reference)
- **MCP tool reference**: [usekeel.io/docs/sdk/tool-reference](https://usekeel.io/docs/sdk/tool-reference)
- **REST API reference**: [usekeel.io/docs/api-reference](https://usekeel.io/docs/api-reference)
- **Agent instructions** (canonical, machine-readable): [`AGENTS.md`](https://github.com/keel-trade/keel-trade/blob/HEAD/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`](https://github.com/keel-trade/keel-trade/blob/HEAD/CONTRIBUTING.md). Short version:

- **Bug report** → open an issue using the bug template
- **Feature request, question, or pattern share** → use [Discussions](https://github.com/keel-trade/keel-trade/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](https://usekeel.io)
- [What is MCP?](https://usekeel.io/learn/what-is-mcp)
- [AI agents on Hyperliquid — the definitive guide](https://usekeel.io/agent/hyperliquid)
- [Why we don't put LLMs in the trade loop](https://usekeel.io/learn/agentic-trading)

## License

MIT. See [`LICENSE`](https://github.com/keel-trade/keel-trade/blob/HEAD/LICENSE).

---

<p align="center">
  Built by <a href="https://usekeel.io/about">the Keel Research Team</a> · <a href="https://x.com/usekeelio">@usekeelio</a>
</p>