Skip to content
Back to search

elysium-chain-mcp

MCP server for AI agents to read and interact with Elysium, Kinetiq’s Arbitrum Orbit L2 on Hyperliquid

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/elysiumforge-labs--elysium-chain-mcp/badge.svg)](/listings/elysiumforge-labs--elysium-chain-mcp)

HTML

<a href="/listings/elysiumforge-labs--elysium-chain-mcp"><img src="/api/listings/elysiumforge-labs--elysium-chain-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The RPC URL and chain ID below are the public testnet values from the [chain specifications](https://elysium.kinetiq.xyz/docs/chain-specifications).

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

Claude Desktop (`claude_desktop_config.json`) and Cursor (`mcp.json`) both use this `mcpServers` object. The default transport is MCP over stdio. The process reads environment variables from the client and does not load a `.env` file. Every variable is listed in [`.env.example`](.env.example).

Local checkout

npm install
npm run build
npm start

Export `ELYSIUM_RPC_URL` and `ELYSIUM_CHAIN_ID` before `npm start`.

HTTP

Set `MCP_TRANSPORT=http` to serve MCP over HTTP. The process binds `127.0.0.1:3000`, accepts `POST /mcp`, and `GET /health` returns `{ "status": "ok" }`.

`MCP_HTTP_TOKEN` (at least 16 characters) is required when the bind address is not loopback, and whenever writes are enabled over HTTP.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 176 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # elysium-chain-mcp
  2. MCP server so AI agents can read and interact with the Elysium chain (Kinetiq's Arbitrum Orbit L2 for Hyperliquid).
  3. Part of [ElysiumForge Labs](https://github.com/ElysiumForge-Labs).
  4. An agent can read blocks, balances, contracts, and logs over JSON-RPC, and can query the block explorer when that API is configured. Sending transactions is a separate switch, and it accepts only Elysium testnet (chain ID `99801`).
  5. Reads follow `ELYSIUM_RPC_URL`. Write tools stay unregistered until `ENABLE_WRITES=true`, and the process accepts them only on chain ID `99801`.
  6. For a first connection, follow [Start here](docs/START.md), then the prompts in [Examples](docs/EXAMPLES.md).
  7. ## Requirements
  8. Node.js 20 or newer.
  9. ## Client setup
  10. The RPC URL and chain ID below are the public testnet values from the [chain specifications](https://elysium.kinetiq.xyz/docs/chain-specifications).
  11. ```json
  12. {
  13. "mcpServers": {
  14. "elysium": {
  15. "command": "npx",
  16. "args": ["-y", "elysium-chain-mcp"],
  17. "env": {
  18. "ELYSIUM_RPC_URL": "https://testnet-rpc.elysium.kinetiq.xyz",
  19. "ELYSIUM_CHAIN_ID": "99801"
  20. }
  21. }
  22. }
  23. }
  24. ```
  25. Claude Desktop (`claude_desktop_config.json`) and Cursor (`mcp.json`) both use this `mcpServers` object. The default transport is MCP over stdio. The process reads environment variables from the client and does not load a `.env` file. Every variable is listed in [`.env.example`](.env.example).
  26. ### Local checkout
  27. ```bash
  28. npm install
  29. npm run build
  30. npm start
  31. ```
  32. Export `ELYSIUM_RPC_URL` and `ELYSIUM_CHAIN_ID` before `npm start`.
  33. ### HTTP
  34. Set `MCP_TRANSPORT=http` to serve MCP over HTTP. The process binds `127.0.0.1:3000`, accepts `POST /mcp`, and `GET /health` returns `{ "status": "ok" }`.
  35. `MCP_HTTP_TOKEN` (at least 16 characters) is required when the bind address is not loopback, and whenever writes are enabled over HTTP.
  36. ## Tools
  37. Eight read tools are always registered. Inputs, outputs, and error codes are in [Tools](docs/TOOLS.md).
  38. | Tool | What it does |
  39. | ------------------ | ---------------------------------------------------------------- |
  40. | `get_chain_status` | Latest block, measured block time, base fee, and gas price |
  41. | `get_block` | One block, by number, tag, or hash |
  42. | `get_transaction` | Transaction, receipt, fee, and optional decoded call and logs |
  43. | `get_balance` | HYPE balance, plus up to 20 ERC-20 balances |
  44. | `get_token_info` | ERC-20 name, symbol, decimals, and total supply |
  45. | `read_contract` | Call a `view` or `pure` function. The call is not submitted |
  46. | `get_logs` | Event logs. Unfiltered queries are capped (default 2,000 blocks) |
  47. | `simulate_call` | `eth_call` plus a gas estimate. Nothing is signed or submitted |
  48. Seven explorer tools register only when `EXPLORER_API_URL` is set. They call an undocumented Blockscout-style API. Indexed balances can lag the chain; the RPC tools are the source of truth. Names, symbols, ABIs, and source code come back under `untrusted`. Detail is in [Explorer tools](docs/EXPLORER.md).
  49. | Tool | What it does |
  50. | ----------------------------------- | ---------------------------------------------- |
  51. | `explorer_get_address` | Indexed overview of an address |
  52. | `explorer_get_address_transactions` | Transactions for an address, newest first |
  53. | `explorer_get_token_transfers` | Token transfers for an address |
  54. | `explorer_get_token_balances` | Tokens the explorer has indexed for an address |
  55. | `explorer_get_contract` | Verification status, ABI, and optional source |
  56. | `explorer_search` | Search by name or address |
  57. | `explorer_get_token` | Token metadata, and holders when requested |
  58. Two write tools register only when `ENABLE_WRITES=true`. Setup and the full check sequence are in [Write tools](docs/WRITES.md).
  59. | Tool | What it does |
  60. | ---------------- | ------------------------------------------------ |
  61. | `send_native` | Send HYPE from the server's testnet account |
  62. | `write_contract` | Call a state-changing function from that account |
  63. Both default to `dry_run: true`. A dry run simulates and returns the exact transaction. Set `dry_run` to `false` to sign and submit.
  64. Amounts in tool output are decimal strings. HYPE uses 18 decimals (1 HYPE = 10^18 wei). Chain IDs, nonces, gas, and logs are covered in [Concepts](docs/CONCEPTS.md).
  65. ## Configuration
  66. | Variable | Required | Default | Purpose |
  67. | -------------------------- | -------------------------------------- | ----------- | --------------------------------------------------------------- |
  68. | `ELYSIUM_RPC_URL` | yes | | HTTP or HTTPS JSON-RPC endpoint |
  69. | `ELYSIUM_CHAIN_ID` | yes | | Chain ID that endpoint must serve |
  70. | `ELYSIUM_CHAIN_NAME` | no | `Elysium` | Display name only |
  71. | `RPC_TIMEOUT_MS` | no | `10000` | Per-attempt RPC timeout |
  72. | `RPC_RETRY_COUNT` | no | `3` | Retries after the first attempt, for transport failures only |
  73. | `RPC_RETRY_BASE_DELAY_MS` | no | `250` | Base delay for exponential backoff with jitter |
  74. | `RPC_RATE_LIMIT_RPS` | no | `10` | Client-side request rate. Retries count against it |
  75. | `MAX_LOG_BLOCK_RANGE` | no | `2000` | Largest unfiltered `get_logs` range, in blocks |
  76. | `BLOCK_TIME_SAMPLE_SIZE` | no | `1000` | Blocks used to measure average block time |
  77. | `MCP_TRANSPORT` | no | `stdio` | `stdio` or `http` |
  78. | `MCP_HTTP_HOST` | no | `127.0.0.1` | HTTP bind address |
  79. | `MCP_HTTP_PORT` | no | `3000` | HTTP port. `0` asks the OS for a free port |
  80. | `MCP_HTTP_TOKEN` | off loopback, and for writes over HTTP | | Bearer token, at least 16 characters |
  81. | `LOG_LEVEL` | no | `info` | `debug`, `info`, `warn`, or `error`. Logs go to stderr |
  82. | `EXPLORER_API_URL` | no | off | Explorer API base, such as `https://elysium.kinetiq.xyz/api/v2` |
  83. | `EXPLORER_TIMEOUT_MS` | no | `10000` | Per-attempt explorer timeout |
  84. | `EXPLORER_RETRY_COUNT` | no | `2` | Explorer retries after the first attempt |
  85. | `EXPLORER_RATE_LIMIT_RPS` | no | `5` | Client-side explorer request rate |
  86. | `ENABLE_WRITES` | no | `false` | Register `send_native` and `write_contract` |
  87. | `ELYSIUM_PRIVATE_KEY` | when writes are on | | 32-byte hex key. Never a tool argument |
  88. | `MAX_SEND_HYPE` | no | `0.01` | Most HYPE one transaction may send |
  89. | `MAX_FEE_HYPE` | no | `0.001` | Most HYPE one transaction may spend on fees |
  90. | `WRITE_ALLOWLIST` | no | any address | Comma-separated destination addresses |
  91. | `WRITE_RECEIPT_TIMEOUT_MS` | no | `30000` | How long a send waits for its receipt |
  92. Logs record only the origin of `ELYSIUM_RPC_URL` and `EXPLORER_API_URL`, so a key in the path or query string stays out of the log line.
  93. ## Risks
  94. Read this before setting `ENABLE_WRITES=true`. The longer version is in [Write tools](docs/WRITES.md#risks-of-the-write-tools).
  95. The server starts with writes enabled only when the key is valid, `ELYSIUM_CHAIN_ID` is `99801`, and HTTP mode has `MCP_HTTP_TOKEN` set. Every write then checks, in order:
  96. 1. The destination is on `WRITE_ALLOWLIST`, when that list is set, and the HYPE value is within `MAX_SEND_HYPE`.
  97. 2. The node reports chain ID `99801`.
  98. 3. `eth_call` from the signing account succeeds. A revert submits nothing.
  99. 4. The gas limit (`eth_estimateGas` plus 20%) times the max fee per gas is within `MAX_FEE_HYPE`.
  100. 5. The account balance covers the value plus that maximum fee.
  101. `dry_run` defaults to true. It is a preview. The agent can pass `dry_run: false` on its own, so leave tool-call approval on in the MCP client for `send_native` and `write_contract`.
  102. Use a dedicated testnet account, funded from the [testnet faucet](https://elysium.kinetiq.xyz/testnet-faucet), holding only what you can afford to lose. The key is read from `ELYSIUM_PRIVATE_KEY` and then removed from the process environment. The client config or secrets file that supplied it still holds the key. Tool arguments, logs, and tool results omit the key.
  103. `WRITE_ALLOWLIST` and `MAX_SEND_HYPE` apply to the top-level transaction. An allowed token contract can still be called with `transfer` or `approve` for any address. Close that gap before enabling writes on any chain that holds real value.
  104. A `pending` status, or `SEND_STATUS_UNKNOWN`, means the transaction may already be in the node. Look it up with `get_transaction` and the hash before submitting it again.
  105. Explorer text and on-chain names are written by third parties and can try to steer the agent. With writes and the explorer both enabled, the server logs a warning at startup. Tool-call approval is the control that stops a steered write.
  106. ## Documentation
  107. | Document | Contents |
  108. | ---------------------------------- | -------------------------------------------------------- |
  109. | [Start here](docs/START.md) | Connect, check the chain, and the first questions to ask |
  110. | [Examples](docs/EXAMPLES.md) | Prompts and the tool input each one should produce |
  111. | [Tools](docs/TOOLS.md) | Inputs, outputs, error codes, RPC retry behaviour |
  112. | [Explorer tools](docs/EXPLORER.md) | Undocumented API, pagination, untrusted fields |
  113. | [Write tools](docs/WRITES.md) | Setup, checks, and risks |
  114. | [Concepts](docs/CONCEPTS.md) | Blocks, wei, gas, logs, and keys |
  115. | [Changelog](CHANGELOG.md) | Released changes |
  116. | [Security](SECURITY.md) | What to report, and how |
  117. ## Development
  118. ```bash
  119. npm install
  120. npm run typecheck
  121. npm test
  122. npm run test:integration # live testnet; set SKIP_INTEGRATION=true to skip
  123. npm run build
  124. ```
  125. `prepublishOnly` runs the typecheck, the unit tests, and the build. Integration tests are opt-in because they call the public testnet. The funded write test runs only when `ELYSIUM_TEST_PRIVATE_KEY` is set. Release steps are in [RELEASING.md](RELEASING.md).
  126. ## Security
  127. Report a vulnerability privately. Omit private keys, including testnet keys. Scope and the known limits are in [SECURITY.md](SECURITY.md).
  128. ---
  129. Unofficial community project. Not affiliated with Kinetiq/Hyperliquid.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.