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