# Etherlink MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8+-3178C6)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-1.22.0+-blue)](https://modelcontextprotocol.io/)

A Model Context Protocol (MCP) server for **Etherlink** - an EVM-compatible Layer 2 blockchain built on Tezos.

## Networks

| Network | Chain ID | RPC Endpoint | Explorer |
|---------|----------|--------------|----------|
| **Mainnet** | 42793 | https://node.mainnet.etherlink.com | [explorer.etherlink.com](https://explorer.etherlink.com) |
| **Shadownet Testnet** | 127823 | https://node.shadownet.etherlink.com | [shadownet.explorer.etherlink.com](https://shadownet.explorer.etherlink.com) |

**Native Currency:** XTZ (18 decimals)

## Quick Start

### Install & Run

```bash
git clone https://github.com/efekucuk/etherlink-mcp-server.git
cd etherlink-mcp-server

bun install
bun run start
```

### Configure with Claude Desktop

Add to your Claude Desktop config (`~/.config/claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "etherlink": {
      "command": "bun",
      "args": ["run", "/path/to/etherlink-mcp-server/src/index.ts"],
      "env": {
        "EVM_PRIVATE_KEY": "your-private-key-here"
      }
    }
  }
}
```

### Network Aliases

- **Mainnet:** `etherlink`, `etherlink-mainnet`
- **Testnet:** `etherlink-shadownet`, `etherlink-testnet`, `shadownet`

## Features

- ✅ Check balances (native XTZ + ERC20 tokens)
- ✅ Send transactions
- ✅ Read/write smart contracts (automatic ABI fetching)
- ✅ Token operations (ERC20, ERC721, ERC1155)
- ✅ Transaction history and receipts
- ✅ Gas estimation
- ✅ Block data access
- ✅ Debug tracing

## Etherlink-Specific Notes

### Key Characteristics

1. **Native Currency:** XTZ (Tez)
2. **EIP-1559 Support:** Yes - uses `max_fee_per_gas`. Priority fees (`max_priority_fee_per_gas`) are ignored since the sequencer uses first-come-first-served ordering.
3. **WebSockets:** Supported when running your own node with `--ws` flag. Public RPC nodes don't expose WebSockets.
4. **Rate Limits:** Public RPC limited to 1000 requests/minute

### Fee Structure

Etherlink fees include:
- **Execution fee** - varies based on network throughput (minimum 1 gwei)
- **Inclusion fee** - covers data availability on Tezos L1

See [Fee structure](https://docs.etherlink.com/network/fees/) for details.

## Testing

```bash
bun test test/etherlink.test.ts
```

## Testnet Faucet

Get testnet XTZ: https://shadownet.faucet.etherlink.com

## Resources

- [Etherlink Documentation](https://docs.etherlink.com/)
- [Block Explorer](https://explorer.etherlink.com)
- [Shadownet Explorer](https://shadownet.explorer.etherlink.com)
- [Governance](https://governance.etherlink.com)

## License

MIT