edgex-mcp

MCP (Model Context Protocol) server for EdgeX perpetual contract trading.

Provides 16 AI agent tools for market data, account management, and order execution. Works with Cursor, Claude Code, OpenClaw, and any MCP-compatible AI client. Use testnet by setting EDGEX_TESTNET=1 in the MCP env (like the CLI --testnet flag).

Setup

Add to your MCP configuration:

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "edgex": {
      "command": "npx",
      "args": ["-y", "@realnaka/edgex-mcp"],
      "env": {
        "EDGEX_ACCOUNT_ID": "your-account-id",
        "EDGEX_STARK_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "edgex": {
      "command": "npx",
      "args": ["-y", "@realnaka/edgex-mcp"],
      "env": {
        "EDGEX_ACCOUNT_ID": "your-account-id",
        "EDGEX_STARK_PRIVATE_KEY": "0x..."
      }
    }
  }
}

OpenClaw (~/.openclaw/openclaw.json):

Prerequisite: OpenClaw does not natively support MCP. Install MCP Porter first:

npx clawhub@latest install mcporter

Then configure the MCP server below. MCP Porter acts as a bridge between OpenClaw and MCP servers.

{
  "mcp": {
    "servers": {
      "edgex": {
        "command": "npx",
        "args": ["-y", "@realnaka/edgex-mcp"],
        "env": {
          "EDGEX_ACCOUNT_ID": "your-account-id",
          "EDGEX_STARK_PRIVATE_KEY": "0x..."
        }
      }
    }
  }
}

Market data tools work without credentials. Account and trading tools require EDGEX_ACCOUNT_ID and EDGEX_STARK_PRIVATE_KEY.

Tools

Environment (no auth)

Tool	Description
edgex_get_environment	Current baseUrl, isTestnet, environment ("testnet" | "mainnet"). Call this to confirm testnet vs mainnet before trading.

Market Data (public, no auth)

Tool	Description
edgex_get_ticker	24h ticker: price, volume, OI, funding rate. Omit symbol for multiple contracts.
edgex_get_depth	Order book bids/asks
edgex_get_kline	Candlestick data (1m to 1M intervals)
edgex_get_funding	Current and predicted funding rate
edgex_get_ratio	Long/short ratio from multiple exchanges
edgex_get_summary	Market-wide volume summary

Account (requires auth)

Tool	Description
edgex_get_balances	Account balances, equity, margin
edgex_get_positions	Open positions with unrealized PnL
edgex_get_orders	Active/pending orders
edgex_get_order_status	Status of a specific order
edgex_get_max_size	Max order size given current balance
edgex_set_leverage	Set leverage per contract (cross-margin)

Trading (requires auth)

Tool	Description
edgex_place_order	Place limit/market orders with optional TP/SL
edgex_cancel_order	Cancel orders by ID
edgex_cancel_all_orders	Cancel all orders (optionally by symbol)

Supported Assets

290+ perpetual contracts:

• Crypto: BTC, ETH, SOL, and more
• US Equities: TSLA, AAPL, NVDA, GOOG, AMZN, META, and more

Flexible symbol input: BTC, btc, BTCUSD, or contract ID 10000001.

Environment Variables

Variable	Required	Description
EDGEX_ACCOUNT_ID	For trading	EdgeX account ID
EDGEX_STARK_PRIVATE_KEY	For trading	StarkEx private key
EDGEX_TESTNET	No	Set to 1 for testnet
EDGEX_BASE_URL	No	Override REST API URL
HTTPS_PROXY / https_proxy	No	HTTP proxy URL (see below)

Proxy Configuration

Node.js's built-in fetch does not automatically use system proxy settings ($https_proxy / $http_proxy). If you're behind a proxy (common in China, corporate networks, etc.), requests to the EdgeX API will fail silently.

The MCP server auto-detects proxy env vars at startup and configures fetch accordingly (requires Node.js >= 20 or undici installed). You just need to pass the proxy URL via MCP env config:

{
  "mcpServers": {
    "edgex": {
      "command": "npx",
      "args": ["-y", "@realnaka/edgex-mcp"],
      "env": {
        "HTTPS_PROXY": "http://127.0.0.1:7890",
        "EDGEX_ACCOUNT_ID": "your-account-id",
        "EDGEX_STARK_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Why this is needed: npx spawns a new Node.js process that does not inherit your shell's proxy environment variables. You must explicitly pass HTTPS_PROXY (or HTTP_PROXY) in the MCP env block.

Verify proxy is active: Call edgex_get_environment — the response includes a proxy field showing the active proxy URL or "none".

Security

• Private keys stay on your local machine (never sent to any third-party server)
• The MCP server runs as a local process, communicating via stdin/stdout
• Credentials are passed via environment variables, not stored in config files
• Use sub-account keys and set withdrawal whitelist on your main account

Resources (for AI agents)

The server exposes three MCP Resources that AI agents can read for context:

Resource URI	Content
edgex://trading-rules	Margin, order types, stock contract rules, funding, liquidation
edgex://agent-guidelines	Safe order workflows, key field paths, data parsing rules
edgex://output-schemas	JSON response schemas for all tools

AI clients (Cursor, Claude Code) will automatically discover these via resources/list and can read them before performing tasks.

EdgeX Tool Ecosystem

This project is part of the EdgeX developer ecosystem. Each project is independent — choose whichever fits your integration scenario:

Project	npm Package	For
edgex-mcp (this)	@realnaka/edgex-mcp	AI agents via MCP protocol (Cursor, Claude Code, OpenClaw)
edgex-cli	@realnaka/edgex-cli	Humans, shell scripts, and AI agents via SKILL.md

Key differences:

• edgex-mcp — structured tool interface, type-safe arguments via MCP protocol, server instructions and resources for AI context. Best for deep AI integration.
• edgex-cli — text-based CLI with --json output, installable SKILL.md for AI agents. Best for shell scripting and human interaction.

Both connect to the same EdgeX exchange API. You can use them together or independently.

---

Full Guide

1. Installation & Configuration

1. Add the edgex entry shown above to your MCP configuration (command + args + optional env).
2. Market data only: You can skip EDGEX_ACCOUNT_ID and EDGEX_STARK_PRIVATE_KEY — all public market data tools work without credentials.
3. Trading & account access: Set EDGEX_ACCOUNT_ID and EDGEX_STARK_PRIVATE_KEY in the MCP env block (use the corresponding credentials for mainnet or testnet).

2. Testnet vs Mainnet

• Mainnet (production): Leave EDGEX_TESTNET unset or set to 0. Connects to https://pro.edgex.exchange with real funds.
• Testnet: Set EDGEX_TESTNET=1 in the MCP env. Connects to https://testnet.edgex.exchange for safe experimentation.

Always call edgex_get_environment first and verify that environment and baseUrl match your expectation before placing any orders.

3. Recommended Workflow

1. Confirm environment: edgex_get_environment → check environment ("mainnet" / "testnet").
2. Check market data: edgex_get_ticker, edgex_get_funding, etc. Omit symbol for a multi-contract overview, or pass BTC, ETH, SOL, etc.
3. Before placing orders: Call edgex_get_balances and edgex_get_max_size to verify balance and available size. Confirm direction, quantity, and price with the user before calling edgex_place_order.
4. Order management: Use edgex_get_orders to list open orders. Use edgex_get_order_status(orderId) for a single order (if it returns found: false, fall back to get_orders). Cancel with edgex_cancel_order or edgex_cancel_all_orders.

4. Troubleshooting: npx Fails to Start

In some environments, npx @realnaka/edgex-mcp may not launch correctly. Use the local build path instead:

"edgex": {
  "command": "node",
  "args": ["/absolute/path/to/edgex-mcp/dist/index.js"],
  "env": { "EDGEX_ACCOUNT_ID": "...", "EDGEX_STARK_PRIVATE_KEY": "0x..." }
}

Alternatively, install globally and run directly:

npm install -g @realnaka/edgex-mcp
# Then use "command": "edgex-mcp" in your MCP config

---

Known Limitations

Issue	Description	Workaround
get_order_status	The backend getOrderById endpoint may return empty in some cases. The MCP returns { orderId, found: false, message: "..." } when this happens.	Use edgex_get_orders to find the order in the full list. The MCP already handles object/array/nested response formats — once the backend returns data, it will be parsed correctly.
npx startup	Some npm versions may not install the bin entry correctly, causing npx @realnaka/edgex-mcp to fail.	Use the node + local dist/index.js approach described above, or install globally with npm install -g.
US equity market orders	Market orders for US equity contracts are rejected outside trading hours. Only limit orders within the allowed price range are accepted.	Use limit orders for equity contracts. See edgex://trading-rules for price range details.
Proxy not inherited	npx / Node.js fetch do not auto-inherit system proxy env vars, causing connection failures behind proxies.	Pass HTTPS_PROXY explicitly in the MCP env config. See Proxy Configuration.
OpenClaw MCP support	OpenClaw does not natively support MCP protocol.	Install MCP Porter first: npx clawhub@latest install mcporter.

---

License

MIT