evm-mcp-server

Provides a single standardized MCP interface that abstracts over 30+ EVM-compatible blockchain networks (Ethereum, Optimism, Arbitrum, Polygon, Base, etc.) through a layered architecture separating protocol interfaces from blockchain services. Uses viem as the underlying Ethereum client library with network-specific RPC endpoint configuration, enabling agents to interact with any supported chain without chain-specific code changes. The architecture maintains a network configuration layer (src/core/chains.ts) that maps chain identifiers to RPC endpoints and metadata, allowing dynamic chain selection at runtime.

Registers blockchain operations as MCP tools through a schema-based function registry that exposes typed, validated tool definitions to LLM clients. Uses Zod for runtime schema validation and the @modelcontextprotocol/sdk to define tool schemas with input/output types, enabling LLMs to understand tool signatures and constraints before invocation. The tools layer (src/core/tools.ts) maps high-level blockchain operations (balance queries, transfers, token interactions, contract calls) to underlying service implementations, with automatic parameter validation and error handling.

Provides MCP prompt templates (defined in src/core/prompts.ts) that guide LLM agents through blockchain operations with pre-written instructions, examples, and best practices. Prompts include operation-specific guidance (e.g., how to safely execute transfers, how to verify contract interactions) and can be customized per chain or operation type. Templates are exposed through the MCP prompt protocol, allowing LLM clients to discover and use them.

Distributes the EVM MCP Server as a public npm package (@mcpdotdirect/evm-mcp-server) with automated build, test, and release processes through GitHub Actions. The release pipeline (defined in .github/workflows/release-publish.yml) automatically builds the package, runs tests, and publishes to npm on version tag creation. Package metadata and entry points are configured in package.json, supporting both CLI usage (npx @mcpdotdirect/evm-mcp-server) and programmatic imports.

Automatically detects the JavaScript runtime (Bun or Node.js) and adapts execution accordingly, with Bun as the primary runtime and Node.js as a supported fallback. The package.json specifies Node.js 18.0.0+ as the minimum version, while the build process targets Bun for optimal performance. Runtime detection allows the server to use runtime-specific optimizations (e.g., Bun's faster module loading) while maintaining compatibility with Node.js environments.

Automatically resolves Ethereum Name Service (ENS) names (e.g., vitalik.eth) to blockchain addresses throughout the tool and resource layers without requiring explicit resolution steps. Integrates ENS resolution into the address parameter handling pipeline, allowing users and LLMs to use human-readable names interchangeably with 0x-prefixed addresses. The ENS service layer (referenced in Services Layer documentation) handles reverse and forward resolution with caching to minimize RPC calls.

Queries native token (ETH) and ERC-20 token balances across 30+ EVM networks through a unified Balance Service that abstracts chain-specific RPC calls. Supports batch balance queries for multiple addresses and tokens, returning structured balance data with token metadata (decimals, symbols). The service layer uses viem's contract reading capabilities to call ERC-20 balanceOf functions and native balance queries, with automatic decimal normalization for human-readable output.

Executes native token (ETH) and ERC-20 token transfers across EVM networks through a Transfer Service that handles transaction construction, gas estimation, and optional pre-execution simulation. Validates recipient addresses, transfer amounts, and gas parameters before submission, using viem's transaction building capabilities. Supports both direct transfers and contract-based transfers (ERC-20 approve + transferFrom pattern), with automatic gas limit calculation and nonce management.

Manages ERC-20 token interactions including balance queries, transfers, and approval workflows through a Token Service that abstracts the ERC-20 standard interface. Handles the approve/allowance pattern required for third-party spending, allowing LLM agents to grant and revoke token spending permissions. Provides token metadata queries (symbol, decimals, total supply) and supports batch token operations across multiple tokens and addresses.

Enables calling arbitrary smart contract functions through a Contract Service that accepts contract ABIs and function signatures, allowing LLM agents to interact with any EVM smart contract. Supports both read-only calls (view/pure functions) and state-changing calls (write functions), with automatic parameter encoding and return value decoding based on ABI definitions. Uses viem's contract reading and writing capabilities to handle low-level ABI encoding/decoding.

Retrieves blockchain data including block information, transaction details, and transaction receipts across EVM networks through Block and Transaction Services. Supports filtering transactions by address, function signature, and status, with automatic parsing of transaction input data and event logs. Uses viem's block and transaction reading capabilities to fetch and decode blockchain data.

Implements a dual-mode MCP server architecture supporting both STDIO (standard input/output) and HTTP transports, enabling integration with different client types and deployment scenarios. The server entry point (src/index.ts) detects the execution environment and automatically selects the appropriate transport, while an HTTP server implementation (src/server/http-server.ts) provides REST-like access for non-STDIO clients. Both transports expose the same MCP protocol interface, ensuring consistent behavior regardless of transport mechanism.

Exposes blockchain state as MCP resources that provide read-only snapshots of on-chain data without requiring tool invocation. Resources (defined in src/core/resources.ts) include network information, token metadata, contract state, and transaction history, allowing LLM clients to access data through the MCP resource protocol rather than tool calls. Resources are refreshed on-demand and can be cached to reduce RPC calls.