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