MCP Etherscan Server

Instructions

Implementation Reference

• src/server.ts:169-185 (handler)

  Executes the "check-balance" tool: validates input address, fetches balance from EtherscanService, formats and returns the response.

  if (name === "check-balance") {
    try {
      const { address } = AddressSchema.parse(args);
      const balance = await etherscanService.getAddressBalance(address);
      const response = `Address: ${balance.address}\nBalance: ${balance.balanceInEth} ETH`;
      return {
        content: [{ type: "text", text: response }],
      };
    } catch (error) {
      if (error instanceof z.ZodError) {
        throw new Error(
          `Invalid input: ${error.errors.map((e) => e.message).join(", ")}`
        );
      }
      throw error;
    }
  }

• src/services/etherscanService.ts:36-62 (helper)

  Core implementation fetching ETH balance using ethers.EtherscanProvider.getBalance and formatting to ETH.

  async getAddressBalance(address: string): Promise<{
    address: string;
    balanceInWei: bigint;
    balanceInEth: string;
  }> {
    try {
      // Validate the address
      const validAddress = ethers.getAddress(address);
      
      // Get balance in Wei
      const balanceInWei = await this.provider.getBalance(validAddress);
      
      // Convert to ETH
      const balanceInEth = ethers.formatEther(balanceInWei);
  
      return {
        address: validAddress,
        balanceInWei,
        balanceInEth
      };
    } catch (error) {
      if (error instanceof Error) {
        throw new Error(`Failed to get balance: ${error.message}`);
      }
      throw error;
    }
  }

• src/server.ts:66-80 (registration)

  Registers the "check-balance" tool in the listTools response with name, description, and input schema.

  {
    name: "check-balance",
    description: "Check the ETH balance of an Ethereum address",
    inputSchema: {
      type: "object",
      properties: {
        address: {
          type: "string",
          description: "Ethereum address (0x format)",
          pattern: "^0x[a-fA-F0-9]{40}$",
        },
      },
      required: ["address"],
    },
  },

• src/server.ts:36-40 (schema)

  Zod schema for validating the Ethereum address input used in the check-balance handler.

  const AddressSchema = z.object({
    address: z
      .string()
      .regex(/^0x[a-fA-F0-9]{40}$/, "Invalid Ethereum address format"),
  });