tools-ethereum

A comprehensive Ethereum toolkit providing both a CLI interface and an MCP (Model Context Protocol) server for blockchain interactions.

Features

• Dual Interface: Use as a command-line tool (ecli) or as an MCP server for AI assistants
• 20+ Ethereum Tools: Complete coverage for reading blockchain data, sending transactions, and interacting with smart contracts
• Type-Safe: Written in TypeScript with Zod schema validation
• Modern Stack: Built on Viem for reliable Ethereum interactions

Installation

npm install tools-ethereum
# or
pnpm add tools-ethereum
# or
yarn add tools-ethereum

CLI Usage

The package provides the ecli command-line interface:

# Start the MCP server with prefixed env vars
export ECLI_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
export ECLI_PRIVATE_KEY=0x...
ecli mcp

# Or use generic env var names (fallback)
export RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
export PRIVATE_KEY=0x...
ecli mcp

# Or use --rpc-url option
ecli --rpc-url https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY mcp

# Get ETH balance (uses env var)
ecli get_balance 0x...

# Or specify --rpc-url explicitly
ecli --rpc-url https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY get_balance 0x...

# Get latest block number
ecli get_block_number

Global Options

• --rpc-url <url> - RPC URL for the Ethereum network (optional if env var is set)

Environment Variables

The CLI checks for environment variables in this priority order:

1. ECLI_RPC_URL - RPC URL for the Ethereum network (prefix avoids conflicts)
2. RPC_URL - Fallback RPC URL (generic name for convenience)
3. ECLI_PRIVATE_KEY - Private key for signing transactions (prefix avoids conflicts)
4. PRIVATE_KEY - Fallback private key (generic name for convenience)

Note: Private keys must start with 0x

MCP Server

The MCP server exposes all Ethereum tools via the Model Context Protocol, enabling AI assistants to interact with the blockchain:

import { createServer } from 'tools-ethereum';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { mainnet } from 'viem/chains';

const server = createServer({
  chain: mainnet,
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
});

const transport = new StdioServerTransport();
await server.connect(transport);

Available Tools

Read-Only Operations

| Tool | Description | |------|-------------| | get_balance | Get ETH balance for an address | | get_block_number | Get the latest block number | | get_block | Get block details by number or hash | | get_latest_block | Get the latest block details | | get_transaction | Get transaction details by hash | | get_transaction_count | Get nonce/transaction count for an address | | get_gas_price | Get current gas price | | get_fee_history | Get fee history for gas estimation | | get_chain_id | Get the network chain ID | | get_code | Get bytecode at an address | | get_storage_at | Get storage value at a specific slot |

Contract Interactions

| Tool | Description | |------|-------------| | call_contract | Call read-only contract functions (view/pure) | | encode_calldata | Encode function calls for contract interactions | | decode_calldata | Decode transaction input data | | estimate_gas | Estimate gas for transactions |

Transaction Operations (requires PRIVATE_KEY)

| Tool | Description | |------|-------------| | send_transaction | Send ETH or call contract functions | | sign_message | Sign arbitrary messages | | wait_for_transaction_confirmation | Wait for transaction receipt |

Log Queries

| Tool | Description | |------|-------------| | get_contract_logs | Query event logs from contracts | | get_transaction_logs | Get logs from a specific transaction |

Development

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run tests
pnpm test

# Watch mode for development
pnpm dev

# Format code
pnpm format

Testing

The project uses Vitest for testing with Prool for local Ethereum node testing:

# Run all tests
pnpm test

# Run with deprecation tracing
pnpm test:trace

# Watch mode
pnpm test:watch

Project Structure

src/
├── index.ts           # Main MCP server creation
├── cli.ts             # CLI entry point
├── cli-tool-generator.ts  # Dynamic CLI command generation
├── helpers.ts         # Client creation and tool registration utilities
├── types.ts           # TypeScript type definitions
└── tools/             # Individual tool implementations
    ├── index.ts       # Tool exports
    ├── get_balance.ts
    ├── send_transaction.ts
    └── ... (20 tools total)

Architecture

The project follows a modular tool-based architecture:

1. Tools (src/tools/*.ts): Self-contained units with schema, description, and execute function
2. MCP Server (src/index.ts): Aggregates all tools into an MCP-compatible server
3. CLI (src/cli.ts): Exposes tools as command-line commands
4. Helpers (src/helpers.ts): Shared utilities for client creation and tool registration

License

MIT © Ronan Sandford

Contributing

Contributions are welcome! Please ensure your changes:

1. Follow the existing code style (run pnpm format)
2. Include appropriate tests
3. Maintain TypeScript type safety
4. Follow the tool pattern with Zod schemas

Resources

• Viem Documentation
• MCP Specification