etherlink

Etherlink MCP Server exposes an MCP-compliant interface to interact with the Etherlink EVM-compatible Layer 2. It supports common RPC capabilities such as checking balances (including ERC20-like tokens), sending transactions, reading/writing smart contracts (with automatic ABI fetching), token operations (ERC20, ERC721, ERC1155), transaction history and receipts, gas estimation, and access to block data and debug tracing. To run it, you typically start the server via your package manager (in this setup, Bun) and point your MCP-enabled clients to the Etherlink MCP server endpoint. The included Claude Desktop integration example shows how to register the Etherlink server in a local Claude configuration, enabling you to query balances, send transactions, and interact with contracts directly from Claude.

Once running, you can perform standard MCP actions such as eth_call/eth_getBalance, eth_sendRawTransaction, and contract interaction calls, all routed through Etherlink’s L2/Audit-friendly backend. The server is designed to work with both Mainnet-like and Shadownet-like test networks, with appropriate network metadata exposed via the MCP layers and detectable via the available RPC endpoints. WebSocket support is available when running your own node with the --ws flag, though public RPC endpoints may not expose WebSockets. Rate limits on public RPC endpoints are noted, so consider running your own node for higher throughput and lower latency.

Prerequisites:

• Node.js or Bun installed (this server example uses Bun in the Quick Start)
• Access to a development environment with internet to install dependencies
• Git client

Installation steps:

1. Clone the repository: git clone https://github.com/efekucuk/etherlink-mcp-server.git cd etherlink-mcp-server

2. Install dependencies (using Bun as shown in the Quick Start): bun install

3. Build or prepare the server (if applicable). If a build script exists, run it. Otherwise, you can start directly with Bun as shown below.

4. Run the server (example shown): bun run start

5. Configure a MCP client to connect to the Etherlink MCP server using the provided mcp_config snippet. Ensure you populate environment variables like EVM_PRIVATE_KEY securely.

Notes:

• If you prefer npm or yarn, adapt the commands accordingly (e.g., npm install, npm run start) as long as the entry point remains valid.
• Ensure your environment has network access to the Etherlink networks (Mainnet or Shadownet) endpoints referenced by the server.

Tips and considerations:

• Environment variables: EVM_PRIVATE_KEY should be kept secret. Do not commit it to version control. Use environment management or secret storage where possible.
• Network aliases: Use the documented aliases for Mainnet (etherlink, etherlink-mainnet) and Testnet (etherlink-shadownet, etherlink-testnet, shadownet) to simplify configuration.
• WebSockets: If you need real-time updates, run your own node with --ws enabled to expose WebSocket RPCs. Public nodes may not offer WebSocket endpoints.
• Rate limits: Public RPC limits are described in the Etherlink docs; running a private node reduces throttling and improves reliability.
• Troubleshooting: Common issues include misconfigured env vars, incorrect path to the index.ts entry, and network endpoint reachability. Verify the path in the mcp_config matches your actual source file location.