Skip to content

Commit 796245b

Browse files
wayzeekwayzeek
committed
feat: updated docs
1 parent 3b7bac3 commit 796245b

2 files changed

Lines changed: 120 additions & 37 deletions

File tree

‎README.md‎

Lines changed: 118 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
# EVM MCP Server
22

33
![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
4-
![EVM Networks](https://img.shields.io/badge/Networks-30+-green)
5-
![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6)
6-
![Viem](https://img.shields.io/badge/Viem-1.0+-green)
4+
![EVM Networks](https://img.shields.io/badge/Networks-60+-green)
5+
![TypeScript](https://img.shields.io/badge/TypeScript-5.8+-3178C6)
6+
![MCP](https://img.shields.io/badge/MCP-1.22.0+-blue)
7+
![Viem](https://img.shields.io/badge/Viem-2.39.3+-green)
78

8-
A comprehensive Model Context Protocol (MCP) server that provides blockchain services across multiple EVM-compatible networks. This server enables AI agents to interact with Ethereum, Optimism, Arbitrum, Base, Polygon, and many other EVM chains with a unified interface.
9+
A comprehensive Model Context Protocol (MCP) server that provides blockchain services across 60+ EVM-compatible networks. This server enables AI agents to interact with Ethereum, Optimism, Arbitrum, Base, Polygon, and many other EVM chains with a unified interface through 21 tools and 9 AI-guided prompts.
910

1011
## 📋 Contents
1112

@@ -14,10 +15,13 @@ A comprehensive Model Context Protocol (MCP) server that provides blockchain ser
1415
- [Supported Networks](#supported-networks)
1516
- [Prerequisites](#prerequisites)
1617
- [Installation](#installation)
17-
- [Server Configuration](#server-configuration)
18+
- [Configuration](#configuration)
19+
- [Environment Variables](#environment-variables)
20+
- [Server Configuration](#server-configuration)
1821
- [Usage](#usage)
1922
- [API Reference](#api-reference)
2023
- [Tools](#tools)
24+
- [Prompts](#prompts)
2125
- [Resources](#resources)
2226
- [Security Considerations](#security-considerations)
2327
- [Project Structure](#project-structure)
@@ -29,19 +33,20 @@ A comprehensive Model Context Protocol (MCP) server that provides blockchain ser
2933
The MCP EVM Server leverages the Model Context Protocol to provide blockchain services to AI agents. It supports a wide range of services including:
3034

3135
- Reading blockchain state (balances, transactions, blocks, etc.)
32-
- Interacting with smart contracts
36+
- Interacting with smart contracts with **automatic ABI fetching** from block explorers
3337
- Transferring tokens (native, ERC20, ERC721, ERC1155)
3438
- Querying token metadata and balances
35-
- Chain-specific services across 30+ EVM networks
39+
- Chain-specific services across 60+ EVM networks (34 mainnets + 26 testnets)
3640
- **ENS name resolution** for all address parameters (use human-readable names like 'vitalik.eth' instead of addresses)
41+
- **AI-friendly prompts** that guide agents through complex workflows
3742

38-
All services are exposed through a consistent interface of MCP tools and resources, making it easy for AI agents to discover and use blockchain functionality. **Every tool that accepts Ethereum addresses also supports ENS names**, automatically resolving them to addresses behind the scenes.
43+
All services are exposed through a consistent interface of MCP tools, resources, and prompts, making it easy for AI agents to discover and use blockchain functionality. **Every tool that accepts Ethereum addresses also supports ENS names**, automatically resolving them to addresses behind the scenes. The server includes intelligent ABI fetching, eliminating the need to know contract ABIs in advance.
3944

4045
## ✨ Features
4146

4247
### Blockchain Data Access
4348

44-
- **Multi-chain support** for 30+ EVM-compatible networks
49+
- **Multi-chain support** for 60+ EVM-compatible networks (34 mainnets + 26 testnets)
4550
- **Chain information** including blockNumber, chainId, and RPCs
4651
- **Block data** access by number, hash, or latest
4752
- **Transaction details** and receipts with decoded logs
@@ -73,6 +78,8 @@ All services are exposed through a consistent interface of MCP tools and resourc
7378
- **Write services** with private key signing
7479
- **Contract verification** to distinguish from EOAs
7580
- **Event logs** retrieval and filtering
81+
- **Automatic ABI fetching** from Etherscan v2 API across all 60+ networks (no need to know ABIs in advance)
82+
- **ABI parsing and validation** with function discovery
7683

7784
### Comprehensive Transaction Support
7885

@@ -81,6 +88,15 @@ All services are exposed through a consistent interface of MCP tools and resourc
8188
- **Transaction status** and receipt information
8289
- **Error handling** with descriptive messages
8390

91+
### AI-Guided Workflows (Prompts)
92+
93+
- **Transaction preparation** - Guidance for planning and executing transfers
94+
- **Wallet analysis** - Tools for analyzing wallet activity and holdings
95+
- **Smart contract exploration** - Interactive ABI fetching and contract analysis
96+
- **Network information** - Learning about EVM networks and comparisons
97+
- **Approval auditing** - Reviewing and managing token approvals
98+
- **Error diagnosis** - Troubleshooting transaction failures
99+
84100
## 🌐 Supported Networks
85101

86102
### Mainnets
@@ -144,8 +160,9 @@ All services are exposed through a consistent interface of MCP tools and resourc
144160

145161
## 🛠️ Prerequisites
146162

147-
- [Bun](https://bun.sh/) 1.0.0 or higher
148-
- Node.js 18.0.0 or higher (if not using Bun)
163+
- [Bun](https://bun.sh/) 1.0.0 or higher (recommended)
164+
- Node.js 20.0.0 or higher (if not using Bun)
165+
- Optional: [Etherscan API key](https://etherscan.io/apis) for ABI fetching
149166

150167
## 📦 Installation
151168

@@ -161,7 +178,41 @@ bun install
161178
npm install
162179
```
163180

164-
## ⚙️ Server Configuration
181+
## ⚙️ Configuration
182+
183+
### Environment Variables
184+
185+
The server uses the following environment variables. For write operations and ABI fetching, you must configure these variables:
186+
187+
#### Private Key (For Write Operations)
188+
189+
```bash
190+
export EVM_PRIVATE_KEY="0x..." # Your private key in hex format (with or without 0x prefix)
191+
```
192+
193+
This private key is used for:
194+
- Transferring native tokens (`transfer_native` tool)
195+
- Transferring ERC20 tokens (`transfer_erc20` tool)
196+
- Approving token spending (`approve_token_spending` tool)
197+
198+
⚠️ **Security**: Never commit your private key to version control. Use environment variables or a secure key management system.
199+
200+
#### API Keys (For ABI Fetching)
201+
202+
```bash
203+
export ETHERSCAN_API_KEY="your-api-key-here"
204+
```
205+
206+
This API key is optional but required for:
207+
- Automatic ABI fetching from block explorers (`get_contract_abi` tool)
208+
- Auto-fetching ABIs when reading contracts (`read_contract` tool with `abiJson` parameter)
209+
- The `fetch_and_analyze_abi` prompt
210+
211+
Get your free API key from:
212+
- [Etherscan](https://etherscan.io/apis) - For Ethereum and compatible chains
213+
- The same key works across all 60+ EVM networks via the Etherscan v2 API
214+
215+
### Server Configuration
165216

166217
The server uses the following default configuration:
167218

@@ -389,36 +440,68 @@ console.log(result);
389440

390441
### Tools
391442

392-
The server provides the following MCP tools for agents. **All tools that accept address parameters support both Ethereum addresses and ENS names.**
443+
The server provides 21 focused MCP tools for agents. **All tools that accept address parameters support both Ethereum addresses and ENS names.**
444+
445+
#### Wallet Information
446+
447+
| Tool Name | Description | Key Parameters |
448+
|-----------|-------------|----------------|
449+
| `get_wallet_address` | Get the address of the configured wallet (from EVM_PRIVATE_KEY) | none |
450+
451+
#### Network Information
452+
453+
| Tool Name | Description | Key Parameters |
454+
|-----------|-------------|----------------|
455+
| `get_chain_info` | Get network information | `network` |
456+
| `get_supported_networks` | List all supported EVM networks | none |
457+
| `get_gas_price` | Get current gas prices on a network | `network` |
393458

394-
#### Token services
459+
#### ENS Services
395460

396461
| Tool Name | Description | Key Parameters |
397462
|-----------|-------------|----------------|
398-
| `get-token-info` | Get ERC20 token metadata | `tokenAddress` (address/ENS), `network` |
399-
| `get-token-balance` | Check ERC20 token balance | `tokenAddress` (address/ENS), `ownerAddress` (address/ENS), `network` |
400-
| `transfer-token` | Transfer ERC20 tokens | `privateKey`, `tokenAddress` (address/ENS), `toAddress` (address/ENS), `amount`, `network` |
401-
| `approve-token-spending` | Approve token allowances | `privateKey`, `tokenAddress` (address/ENS), `spenderAddress` (address/ENS), `amount`, `network` |
402-
| `get-nft-info` | Get NFT metadata | `tokenAddress` (address/ENS), `tokenId`, `network` |
403-
| `check-nft-ownership` | Verify NFT ownership | `tokenAddress` (address/ENS), `tokenId`, `ownerAddress` (address/ENS), `network` |
404-
| `transfer-nft` | Transfer an NFT | `privateKey`, `tokenAddress` (address/ENS), `tokenId`, `toAddress` (address/ENS), `network` |
405-
| `get-nft-balance` | Count NFTs owned | `tokenAddress` (address/ENS), `ownerAddress` (address/ENS), `network` |
406-
| `get-erc1155-token-uri` | Get ERC1155 metadata | `tokenAddress` (address/ENS), `tokenId`, `network` |
407-
| `get-erc1155-balance` | Check ERC1155 balance | `tokenAddress` (address/ENS), `tokenId`, `ownerAddress` (address/ENS), `network` |
408-
| `transfer-erc1155` | Transfer ERC1155 tokens | `privateKey`, `tokenAddress` (address/ENS), `tokenId`, `amount`, `toAddress` (address/ENS), `network` |
409-
410-
#### Blockchain services
463+
| `resolve_ens_name` | Resolve ENS name to address | `ensName`, `network` |
464+
| `lookup_ens_address` | Reverse lookup address to ENS name | `address`, `network` |
465+
466+
#### Block & Transaction Information
467+
468+
| Tool Name | Description | Key Parameters |
469+
|-----------|-------------|----------------|
470+
| `get_block` | Get block data | `blockNumber` or `blockHash`, `network` |
471+
| `get_latest_block` | Get latest block data | `network` |
472+
| `get_transaction` | Get transaction details | `txHash`, `network` |
473+
| `get_transaction_receipt` | Get transaction receipt with logs | `txHash`, `network` |
474+
| `wait_for_transaction` | Wait for transaction confirmation | `txHash`, `confirmations`, `network` |
475+
476+
#### Balance & Token Information
477+
478+
| Tool Name | Description | Key Parameters |
479+
|-----------|-------------|----------------|
480+
| `get_balance` | Get native token balance | `address` (address/ENS), `network` |
481+
| `get_token_balance` | Check ERC20 token balance | `tokenAddress` (address/ENS), `ownerAddress` (address/ENS), `network` |
482+
| `get_allowance` | Check token spending allowance | `tokenAddress` (address/ENS), `ownerAddress` (address/ENS), `spenderAddress` (address/ENS), `network` |
483+
484+
#### Smart Contract Interactions
485+
486+
| Tool Name | Description | Key Parameters |
487+
|-----------|-------------|----------------|
488+
| `get_contract_abi` | Fetch contract ABI from block explorer (60+ networks) | `contractAddress` (address/ENS), `network` |
489+
| `read_contract` | Read smart contract state (auto-fetches ABI if needed) | `contractAddress`, `functionName`, `args[]`, `abiJson` (optional), `network` |
490+
491+
#### Token Transfers
492+
493+
| Tool Name | Description | Key Parameters |
494+
|-----------|-------------|----------------|
495+
| `transfer_native` | Send native tokens (ETH, etc.) | `to` (address/ENS), `amount`, `network` |
496+
| `transfer_erc20` | Transfer ERC20 tokens | `tokenAddress` (address/ENS), `to` (address/ENS), `amount`, `network` |
497+
| `approve_token_spending` | Approve token allowances | `tokenAddress` (address/ENS), `spenderAddress` (address/ENS), `amount`, `network` |
498+
499+
#### NFT Services
411500

412501
| Tool Name | Description | Key Parameters |
413502
|-----------|-------------|----------------|
414-
| `get-chain-info` | Get network information | `network` |
415-
| `get-balance` | Get native token balance | `address` (address/ENS), `network` |
416-
| `transfer-eth` | Send native tokens | `privateKey`, `to` (address/ENS), `amount`, `network` |
417-
| `get-transaction` | Get transaction details | `txHash`, `network` |
418-
| `read-contract` | Read smart contract state | `contractAddress` (address/ENS), `abi`, `functionName`, `args`, `network` |
419-
| `write-contract` | Write to smart contract | `contractAddress` (address/ENS), `abi`, `functionName`, `args`, `privateKey`, `network` |
420-
| `is-contract` | Check if address is a contract | `address` (address/ENS), `network` |
421-
| `resolve-ens` | Resolve ENS name to address | `ensName`, `network` |
503+
| `get_nft_info` | Get NFT (ERC721) metadata | `tokenAddress` (address/ENS), `tokenId`, `network` |
504+
| `get_erc1155_balance` | Check ERC1155 balance | `tokenAddress` (address/ENS), `tokenId`, `ownerAddress` (address/ENS), `network` |
422505

423506
### Resources
424507

‎package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
"module": "src/index.ts",
44
"type": "module",
55
"version": "2.0.0",
6-
"description": "MCP server for interacting with EVM-compatible blockchains - supports 28 tools across 86+ networks",
6+
"description": "MCP server for interacting with EVM-compatible blockchains - supports 21 tools and 9 prompts across 60+ networks",
77
"bin": {
88
"evm-mcp-server": "./bin/cli.js"
99
},
@@ -70,4 +70,4 @@
7070
"publishConfig": {
7171
"access": "public"
7272
}
73-
}
73+
}

0 commit comments

Comments
 (0)