ElysiumForge-Labs/elysium-chain-mcp

Overview

Elysium Chain MCP is a TypeScript MCP server that gives AI agents access to Elysium, Kinetiq's Arbitrum Orbit L2 for Hyperliquid. Agents can read blocks, transactions, balances, token metadata, contract state, and event logs over JSON-RPC; optionally, they can query a block explorer API. Read tools work against the endpoint in ELYSIUM_RPC_URL, while write tools remain unregistered unless both ENABLE_WRITES=true and the chain ID is 99801 (Elysium testnet).

The project is described as an unofficial community project, not affiliated with Kinetiq or Hyperliquid.

Quick start

You need Node.js 20 or newer. The simplest setup is to add the server to your MCP client configuration. Both Claude Desktop (claude_desktop_config.json) and Cursor (mcp.json) use the same mcpServers object:

{
  "mcpServers": {
    "elysium": {
      "command": "npx",
      "args": ["-y", "elysium-chain-mcp"],
      "env": {
        "ELYSIUM_RPC_URL": "https://testnet-rpc.elysium.kinetiq.xyz",
        "ELYSIUM_CHAIN_ID": "99801"
      }
    }
  }
}

The RPC URL and chain ID are the public testnet values from the chain specifications. The default transport is MCP over stdio; the process reads environment variables from the client and does not load a .env file.

For a local checkout, run npm install, npm run build, and npm start after exporting ELYSIUM_RPC_URL and ELYSIUM_CHAIN_ID. To serve over HTTP, set MCP_TRANSPORT=http; the process binds 127.0.0.1:3000, accepts POST /mcp, and exposes GET /health. For the first connection and example prompts, follow the project's Start here guide and Examples docs.

Tools and configuration

Eight read tools are always registered: chain status, block lookup, transaction and receipt lookup, HYPE and ERC-20 balances, token info, view/pure contract calls, event logs, and simulate_call for eth_call plus gas estimation. Unfiltered log queries default to a 2,000-block cap, adjustable via MAX_LOG_BLOCK_RANGE.

Seven explorer tools register only when EXPLORER_API_URL is set. They call an undocumented Blockscout-style API; indexed data can lag the chain, so the RPC tools are treated as the source of truth. Names, symbols, ABIs, and source code returned by the explorer are marked untrusted.

With ENABLE_WRITES=true, two write tools appear: send_native and write_contract. Both default to dry_run: true, which simulates and returns the transaction without signing. Setting dry_run to false signs and submits. The full variable list is in .env.example; retry, timeout, rate-limit, and transport settings are documented in the configuration table.

Use constraints

Writes are testnet-only: the server refuses to start writes unless the chain ID is 99801, the private key is valid, and HTTP mode has an MCP_HTTP_TOKEN of at least 16 characters. Each write checks the optional WRITE_ALLOWLIST, the value cap (MAX_SEND_HYPE, default 0.01 HYPE), the node-reported chain ID, a successful eth_call, the fee cap (MAX_FEE_HYPE, default 0.001 HYPE), and the account balance before submitting.

dry_run is only a preview because the agent can choose dry_run: false itself; the project advises keeping tool-call approval enabled for write tools. Use a dedicated testnet account funded from the testnet faucet and holding only what you can afford to lose. ELYSIUM_PRIVATE_KEY is read from the environment and then removed from the process environment, but the client config or secrets file that supplied it still contains the key.

WRITE_ALLOWLIST and MAX_SEND_HYPE apply only to the top-level transaction; an allowlisted token contract can still be called with transfer or approve for any address. Explorer text and on-chain names are third-party content and can try to steer an agent, so enabling both the explorer and writes causes a startup warning. A pending or unknown send status means the transaction may already be in the node; look it up by hash before resubmitting.

The repository does not declare a license.

HotRepo's take

The project was recorded on HotRepo's new-project list for 4 November 2026 in the TypeScript language view, with 108 stars and 7 stars gained over roughly two hours of observation. Forks remained at zero. That growth window is short, and the server is aimed at a narrow audience: people giving an AI agent read access to the Elysium testnet, or experimenting with tightly capped write access. The design puts substantial safeguards around writes—testnet-only enforcement, dry runs, value and fee caps, and allowlists—while acknowledging that allowlists do not cover token-level approvals. Those limits are the most useful part of the repository for anyone evaluating whether to enable writes at all.