Configuration

June 25, 2026 · View on GitHub

One-Line Install

For a guided installation that handles Node.js checking, package installation, and MCP client detection:

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/okx/agent-tradekit/master/scripts/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/okx/agent-tradekit/master/scripts/install.ps1 | iex

The installer will:

  1. Check Node.js >= 18 (with install guidance if missing)
  2. Install @okx_ai/okx-trade-mcp and @okx_ai/okx-trade-cli globally
  3. Verify installation
  4. Detect installed MCP clients (Claude Desktop, Cursor, Windsurf)
  5. Auto-configure detected clients

After installation, configure your API credentials:

okx config init

API Credentials

All credentials are stored in ~/.okx/config.toml. The client config only needs the profile name.

The easiest way to set this up is the interactive wizard:

okx config init

Or configure manually with a minimal single-profile setup:

default_profile = "demo"

[profiles.demo]
api_key = "your-demo-api-key"
secret_key = "your-demo-secret-key"
passphrase = "your-demo-passphrase"
demo = true

Demo key: Create API Key (Demo Trading)

Live key: Create API Key (Live Trading)

EEA users: replace www.okx.com with my.okx.com · US users: use app.okx.com · TR users: use tr.okx.com

Required API permissions: Read + Trade. Withdraw permission is not required or recommended.

Site Configuration

OKX operates independent regional sites. Users must use the API of the site where their account is registered.

SiteUser URLAPI Base URL
global (default)www.okx.comhttps://www.okx.com
eeamy.okx.comhttps://eea.okx.com
usapp.okx.comhttps://app.okx.com
trtr.okx.comhttps://tr.okx.com

Set the site in your profile:

[profiles.main]
site = "global"          # global | eea | us | tr  (default: global)
api_key = "your-api-key"
secret_key = "your-secret-key"
passphrase = "your-passphrase"

Or override at startup via flag or env var:

# Flag
agent-tradekit-mcp --site eea

# Environment variable (useful in Docker / CI)
OKX_SITE=us agent-tradekit-mcp

Priority: --site flag > OKX_SITE env var > site in toml > default global

Note: OKX_API_BASE_URL / base_url in toml still override the site mapping entirely — useful for testing against a custom endpoint.

Proxy Configuration

Configure an HTTP/HTTPS proxy in your profile:

[profiles.default]
api_key = "your-api-key"
secret_key = "your-secret-key"
passphrase = "your-passphrase"
proxy_url = "http://127.0.0.1:7890"

Authenticated proxies are supported — include credentials in the URL:

[profiles.default]
proxy_url = "http://user:password@proxy.example.com:8080"

# Special characters in password need URL encoding, e.g. p@ss → p%40ss
# proxy_url = "http://user:p%40ss@proxy.example.com:8080"

Note: Only HTTP/HTTPS proxies are supported. SOCKS proxies are not supported.

Multiple profiles

You can define as many profiles as you like. Each MCP server instance uses one profile, so you can run demo and live side by side:

default_profile = "demo"

[profiles.demo]
api_key = "your-demo-api-key"
secret_key = "your-demo-secret-key"
passphrase = "your-demo-passphrase"
demo = true

[profiles.live]
api_key = "your-live-api-key"
secret_key = "your-live-secret-key"
passphrase = "your-live-passphrase"

# Optional: a second live account (e.g. sub-account)
[profiles.live-sub]
api_key = "your-sub-api-key"
secret_key = "your-sub-secret-key"
passphrase = "your-sub-passphrase"

Then register each as a separate MCP server in your client config:

{
  "mcpServers": {
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    },
    "okx-live": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all"]
    },
    "okx-live-sub": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live-sub", "--modules", "all"]
    }
  }
}

Your AI can switch between them simply by calling tools on the appropriate server.

Setup Command

The fastest way to configure a client is the setup subcommand — no manual JSON editing required.

# Configure Claude Desktop
okx-trade-mcp setup --client claude-desktop

# Configure Cursor
okx-trade-mcp setup --client cursor

# Configure VS Code (writes .mcp.json in current directory)
okx-trade-mcp setup --client vscode

# Configure Claude Code CLI
okx-trade-mcp setup --client claude-code

# Use a specific profile and modules
okx-trade-mcp setup --client claude-desktop --profile live --modules market,spot,account

Also available as okx setup --client <client> if okx-trade-cli is installed.

--clientTarget
claude-desktop~/Library/Application\ Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\... (Windows)
cursor~/.cursor/mcp.json
windsurf~/.codeium/windsurf/mcp_config.json
vscode.mcp.json in current directory
claude-coderuns claude mcp add

The command reads existing config and merges the new entry — it will not overwrite other MCP servers.

Client Setup (Manual)

Claude Desktop

Config file:

  • macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "okx-live": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all"]
    },
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

Restart Claude Desktop after updating the config.

Cursor

Config file: ~/.cursor/mcp.json (global) or .cursor/mcp.json (project-level)

⚠️ Cursor tool limit: Cursor enforces a client-side limit of ~40 tools per MCP server and ~80 tools total (as of early 2026). okx-trade-mcp exposes 128 tools across 13 modules — loading --modules all will cause all MCP servers to show Error status. You must select a subset using --modules.

Recommended module combinations:

Use caseModulesTools
Trading (spot + swap)market,account,spot,swap61
Contract + Botmarket,account,swap,bot.grid,bot.dca55
Earnmarket,account,earn.savings,earn.onchain,earn.dcd,earn.autoearn48
Minimal (market data + account)market,account27

Tip: If you need more modules than fit in one server, register multiple server instances with different --modules sets. Tool counts from all servers are pooled toward the ~80-tool total, so plan your splits accordingly.

{
  "mcpServers": {
    "okx-trade": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "market,account,spot,swap"]
    }
  }
}

Or use the setup command with an explicit module list:

okx-trade-mcp setup --client cursor --modules market,account,spot,swap

Claude Code CLI

claude mcp add --transport stdio okx-trade-mcp -- okx-trade-mcp --profile demo --modules all

Or create .mcp.json in your project root:

{
  "mcpServers": {
    "okx-trade-mcp": {
      "type": "stdio",
      "command": "okx-trade-mcp",
      "args": ["--profile", "demo", "--modules", "all"]
    }
  }
}

VS Code

Create .mcp.json in your project root (or ~/.claude.json for global scope):

{
  "mcpServers": {
    "okx-trade-mcp": {
      "type": "stdio",
      "command": "okx-trade-mcp",
      "args": ["--profile", "demo", "--modules", "all"]
    }
  }
}

Windsurf

Config file:

  • macOS/Linux: ~/.codeium/windsurf/mcp_config.json
  • Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
{
  "mcpServers": {
    "okx-trade-mcp": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

openCxxW

Config file: openCxxW.json

{
  "mcpServers": {
    "okx-live": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all"]
    },
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

Startup Scenarios

Market data only (no API key required)

Watch prices, orderbook, candles without any credentials:

{
  "mcpServers": {
    "okx-market": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--modules", "market"]
    }
  }
}

Read-only account monitoring

Has API key but prevents any order placement:

{
  "mcpServers": {
    "okx-readonly": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all", "--read-only"]
    }
  }
}

Spot trading only

Minimal setup for spot trading — skips swap, futures, and bot modules:

{
  "mcpServers": {
    "okx-spot": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "market", "spot", "account"]
    }
  }
}

Demo (simulated trading)

Safe environment for testing — uses OKX paper trading, no real funds at risk:

{
  "mcpServers": {
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

Note: Grid bot tools (bot module) are not supported in demo mode — OKX does not expose those endpoints for simulated trading.

Full setup (live + demo side by side)

Register both as separate MCP servers. Your AI can switch between them:

{
  "mcpServers": {
    "okx-live": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all"]
    },
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

All Startup Options

OptionDescription
--profile <name>Profile from ~/.okx/config.toml (default: value of default_profile)
--modules <list>Comma-separated module names, or all. Default: spot swap account. all includes every module including earn sub-modules.
--read-onlyDisable all write operations (orders, position changes, bot creation)
--no-logDisable audit logging to ~/.okx/logs/
--log-level <level>Minimum log level: debug, info, warn, error (default: info)

配置（中文）

API 凭证

所有凭证存储在 ~/.okx/config.toml，客户端配置只需指定 Profile 名称。

最简单的单账号配置：

default_profile = "demo"

[profiles.demo]
api_key = "your-demo-api-key"
secret_key = "your-demo-secret-key"
passphrase = "your-demo-passphrase"
demo = true

模拟盘 Key： 创建 API Key（模拟盘）

实盘 Key： 创建 API Key（实盘）

EEA 用户：将 www.okx.com 替换为 my.okx.com；US 用户：使用 app.okx.com；TR 用户：使用 tr.okx.com

所需 API 权限： 读取 + 交易。无需也不建议开启提币权限。

站点配置

OKX 运营多个独立的区域站点，用户需要使用其账号所在站点的 API。

站点用户网址API Base URL
global（默认）www.okx.comhttps://www.okx.com
eeamy.okx.comhttps://eea.okx.com
usapp.okx.comhttps://app.okx.com
trtr.okx.comhttps://tr.okx.com

在 Profile 中指定站点：

[profiles.main]
site = "global"          # global | eea | us | tr（默认：global）
api_key = "your-api-key"
secret_key = "your-secret-key"
passphrase = "your-passphrase"

也可以通过命令行参数或环境变量覆盖：

# 命令行参数
agent-tradekit-mcp --site eea

# 环境变量（适用于 Docker / CI）
OKX_SITE=us agent-tradekit-mcp

优先级：--site 参数 > OKX_SITE 环境变量 > toml 中的 site > 默认 global

注意： OKX_API_BASE_URL 环境变量 / toml 中的 base_url 仍然优先级最高，会完全覆盖站点映射——适合高级用户或自定义测试场景。

代理配置

在 Profile 中配置 HTTP/HTTPS 代理：

[profiles.default]
api_key = "your-api-key"
secret_key = "your-secret-key"
passphrase = "your-passphrase"
proxy_url = "http://127.0.0.1:7890"

支持带认证的代理——在 URL 中包含用户名和密码：

[profiles.default]
proxy_url = "http://user:password@proxy.example.com:8080"

# 密码中的特殊字符需要 URL encode，例如 p@ss → p%40ss
# proxy_url = "http://user:p%40ss@proxy.example.com:8080"

注意： 仅支持 HTTP/HTTPS 代理，不支持 SOCKS 代理。

多账号配置

可以定义多个 Profile，每个 MCP Server 实例使用一个 Profile，模拟盘和实盘可以并行运行：

default_profile = "demo"

[profiles.demo]
api_key = "your-demo-api-key"
secret_key = "your-demo-secret-key"
passphrase = "your-demo-passphrase"
demo = true

[profiles.live]
api_key = "your-live-api-key"
secret_key = "your-live-secret-key"
passphrase = "your-live-passphrase"

# 可选：第二个实盘账号（如子账号）
[profiles.live-sub]
api_key = "your-sub-api-key"
secret_key = "your-sub-secret-key"
passphrase = "your-sub-passphrase"

然后在客户端配置中分别注册为独立的 MCP Server：

{
  "mcpServers": {
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    },
    "okx-live": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all"]
    },
    "okx-live-sub": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live-sub", "--modules", "all"]
    }
  }
}

AI 可以直接通过调用对应 Server 的工具来切换账号。

Setup 命令

最快的配置方式是 setup 子命令，无需手动编辑 JSON。

# 配置 Claude Desktop
okx-trade-mcp setup --client claude-desktop

# 配置 Cursor
okx-trade-mcp setup --client cursor

# 配置 VS Code（在当前目录写 .mcp.json）
okx-trade-mcp setup --client vscode

# 配置 Claude Code CLI
okx-trade-mcp setup --client claude-code

# 指定 profile 和模块
okx-trade-mcp setup --client claude-desktop --profile live --modules market,spot,account

安装了 okx-trade-cli 的话，也可以用 okx setup --client <client>。

--client目标
claude-desktopmacOS: ~/Library/Application\ Support/Claude/... / Windows: %APPDATA%\Claude\...
cursor~/.cursor/mcp.json
windsurf~/.codeium/windsurf/mcp_config.json
vscode当前目录下的 .mcp.json
claude-code调用 claude mcp add

命令会读取现有配置并合并写入，不会覆盖其他已有的 MCP Server 条目。

客户端配置（手动）

Claude Desktop

配置文件路径：

  • macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "okx-live": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all"]
    },
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

修改配置后重启 Claude Desktop 生效。

Cursor

配置文件：~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目级）

⚠️ Cursor 工具数量限制：Cursor 客户端限制每个 MCP Server 最多约 40 个工具，所有 Server 合计不超过约 80 个（截至 2026 年初）。okx-trade-mcp 共有 128 个工具（13 个模块），使用 --modules all 将导致所有 MCP Server 显示 Error 状态。必须通过 --modules 参数选择子集。

推荐模块组合：

使用场景模块工具数
交易（现货 + 合约）market,account,spot,swap61
合约 + 机器人market,account,swap,bot.grid,bot.dca55
赚币market,account,earn.savings,earn.onchain,earn.dcd,earn.autoearn48
最小化（行情 + 账户）market,account27

提示： 如果需要的模块超出单个 Server 的工具上限，可以注册多个 Server 实例，每个实例指定不同的 --modules。所有实例的工具数量合计计入约 80 个总限额，规划时需综合考虑。

{
  "mcpServers": {
    "okx-trade": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "market,account,spot,swap"]
    }
  }
}

也可以用 setup 命令指定模块列表：

okx-trade-mcp setup --client cursor --modules market,account,spot,swap

Claude Code CLI

claude mcp add --transport stdio okx-trade-mcp -- okx-trade-mcp --profile demo --modules all

或在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "okx-trade-mcp": {
      "type": "stdio",
      "command": "okx-trade-mcp",
      "args": ["--profile", "demo", "--modules", "all"]
    }
  }
}

VS Code

在项目根目录创建 .mcp.json（或 ~/.claude.json 用于全局配置）：

{
  "mcpServers": {
    "okx-trade-mcp": {
      "type": "stdio",
      "command": "okx-trade-mcp",
      "args": ["--profile", "demo", "--modules", "all"]
    }
  }
}

Windsurf

配置文件：

  • macOS/Linux: ~/.codeium/windsurf/mcp_config.json
  • Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
{
  "mcpServers": {
    "okx-trade-mcp": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

openCxxW

配置文件：openCxxW.json

{
  "mcpServers": {
    "okx-live": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all"]
    },
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

启动场景

仅行情（无需 API Key）

查看价格、盘口、K线，无需任何凭证：

{
  "mcpServers": {
    "okx-market": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--modules", "market"]
    }
  }
}

只读账户监控

有 API Key 但禁止任何下单操作：

{
  "mcpServers": {
    "okx-readonly": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all", "--read-only"]
    }
  }
}

仅现货交易

最小化配置，跳过永续/交割/Bot 模块：

{
  "mcpServers": {
    "okx-spot": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "market", "spot", "account"]
    }
  }
}

模拟盘（模拟交易）

用 OKX 模拟盘安全测试，不涉及真实资金：

{
  "mcpServers": {
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

注意： 网格机器人工具（bot 模块）不支持模拟盘——OKX 不对模拟交易账号开放相关端点。

完整配置（实盘 + 模拟盘并行）

同时注册两个 MCP Server，AI 可自由切换：

{
  "mcpServers": {
    "okx-live": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "live", "--modules", "all"]
    },
    "okx-demo": {
      "command": "npx",
      "args": ["-y", "@okx_ai/okx-trade-mcp", "--profile", "demo", "--modules", "all"]
    }
  }
}

全部启动参数

参数说明
--profile <name>指定 ~/.okx/config.toml 中的 Profile（默认：default_profile 的值）
--modules <list>逗号分隔的模块名，或 all。默认：spot swap account。all 包含所有模块（含赚币子模块）。
--read-only禁用所有写操作（下单、改单、修改仓位、创建/停止 Bot 等）
--no-log禁用审计日志（默认写入 ~/.okx/logs/）
--log-level <level>最低日志级别：debug、info、warn、error（默认：info）