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.

Related MCP server: coinex-mcp-server

Tools

Environment (no auth)

Market Data (public, no auth)

Account (requires auth)

Trading (requires auth)

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

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:

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:

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

License

MIT