OKX MCP server setup

2026-11-09

Figures on this page are as of 2026-09. Fees, limits and margin tiers change — check the venue's own docs before acting on a number.

OKX publishes its own MCP server — okx/agent-trade-kit, under OKX’s GitHub organisation, MIT licensed. That puts it in the small group of venues shipping first-party MCP integrations rather than leaving it to the community.

It is also large: 167 tools across 11 modules, and the default startup configuration includes order placement. The two flags that change that are worth knowing before the first run rather than after.

Install

npm install -g @okx_ai/okx-trade-mcp @okx_ai/okx-trade-cli
okx config init                                    # interactive credential wizard
okx-trade-mcp setup --client claude-desktop        # or cursor | claude-code | vscode

Node.js 18 or later. The vscode target writes .mcp.json in the current directory.

It runs as a local stdio process, and the README states API keys stay on your machine with no cloud services involved. That is the right architecture for this and worth confirming remains true in the version you install.

The two flags that matter

okx-trade-mcp                              # default: spot, swap, account
okx-trade-mcp --modules market             # market data only — no auth needed
okx-trade-mcp --read-only                  # query tools only, no writes
okx-trade-mcp --profile live --modules all # everything, including earn

--read-only restricts the server to query tools. This is the one to start with.

--modules filters which of the eleven modules load at all. --modules market is the strongest position available: market data only, and it needs no API key. You can evaluate whether the whole idea is useful to you without the server ever holding a credential.

The default is spot, swap, account. That includes spot — place, cancel and amend orders — so a first run with configured credentials can trade. This is not hidden, but it is the default, and defaults are what people run.

The modules

Module	Tools	What it covers
`market`	19	Tickers, order books, candles, funding, mark price, open interest, 70+ technical indicators. No auth
`spot`	13	Place / cancel / amend, batch, conditional, OCO
`swap`	17	Perpetuals, positions, leverage, trailing stop
`futures`	18	Delivery contracts, positions, algo orders
`option`	10	Options, Greeks, chains
`account`	14	Balance, bills, positions, fee rates, max withdrawal, audit log
`event`	9	Event contracts
`earn`	24	Simple Earn, on-chain staking, dual investment
`bot`	14	Grid and DCA bots
`news`	7	News and coin sentiment
`smartmoney`	10	Leaderboards and signals — read-only

Fewer modules is less surface. There is no reason to load earn or bot for a setup that is meant to read positions.

Layering it correctly

Module filtering and --read-only are controls inside the server. They are well built and you should use them — but they are configured by you and enforced by the same process you are bounding.

The boundary that does not depend on the server behaving is the API key. OKX keys carry permissions, and the official docs note that the market module needs no key at all, other modules need Read, and write operations additionally need Trade permission.

So the layering is:

--modules market first — no credential at all.
A Read-only OKX key plus --read-only. Two independent controls.
Trade permission only when you have decided you want order placement, and only alongside an approval step in your client.

See read-only vs trade permission for why the key layer is the one that holds.

OKX-specific setup traps

Two things catch people coming from other venues, both covered in the OKX passphrase article:

There is a fourth credential. OKX needs a passphrase alongside key, secret and timestamp. You choose it at key creation and it is not recoverable. okx config init will ask for it; if you did not record it, the key must be replaced.

Demo trading is a header, not a hostname. OKX uses the same host for demo and production, switched by x-simulated-trading: 1. Unlike Binance or Bybit, where testnet lives at a separate address, there is no URL to get wrong — which means there is also no URL protecting you. Confirm which environment your credentials belong to.

When something fails

Errors surface the underlying v5 endpoint and OKX error code, which is a good design decision — it means the troubleshooting you would do against the raw API still applies:

{
  "tool": "swap_place_order",
  "error": true,
  "type": "OkxApiError",
  "code": "51020",
  "endpoint": "POST /api/v5/trade/order"
}

For authentication failures, 50113 is the signature and has its own article; 50102 is clock skew beyond OKX’s 30-second window.

Do not let a failed order retry automatically. A timeout means the outcome is unknown rather than failed — see retrying a failed order is not safe.

FAQ

Does OKX have an official MCP server?

Yes — okx/agent-trade-kit, published under OKX’s own GitHub organisation and MIT licensed, distributed as the npm packages @okx_ai/okx-trade-mcp and @okx_ai/okx-trade-cli. It runs locally as a stdio process rather than as a hosted service.

Does it allow trading by default?

Yes. Running okx-trade-mcp with no flags loads spot, swap and account, and spot includes placing, cancelling and amending orders. Use --read-only for query tools only, or --modules market for market data that needs no API key at all.

Can I use it without giving it my API keys?

Yes, for market data. --modules market loads 19 tools covering tickers, order books, candles, funding rates and technical indicators, and OKX’s documentation notes this module requires no authentication. It is a useful way to evaluate the setup before any credential is involved.

Which OKX key permissions does it need?

Per OKX’s own guidance: none for the market module, Read for the other modules, and Trade permission additionally for write operations. Granting only Read makes order placement impossible regardless of how the server is configured, which is a stronger guarantee than the --read-only flag alone.