Etherscan MCP Tool

Instructions

Implementation Reference

• index.ts:393-432 (handler)

  The handler function that implements the tool logic by querying the Etherscan API for the token holder count using chain_id and token_address.

  async function handleGetTokenHoldersCount(req: any, apiKey: string) {
      const chainId = req.params.arguments.chain_id;
      const tokenAddress = req.params.arguments.token_address;
  
      try {
          const response = await axios.get(
              `https://api.etherscan.io/v2/api?chainid=${chainId}&module=token&action=tokenholdercount&contractaddress=${tokenAddress}&apikey=${apiKey}`
          );
  
          if (response.data.status === "1") {
              const tokenHoldersCount = response.data.result;
              return {
                  content: [
                      {
                          type: "text",
                          text: `Number of token holders for token ${tokenAddress} on chain ${chainId}: ${tokenHoldersCount}`,
                      },
                  ],
              };
          } else {
              return {
                  content: [
                      {
                          type: "text",
                          text: `Failed to get token holders count: ${response.data.message}`,
                      },
                  ],
              };
          }
      } catch (error) {
          return {
              content: [
                  {
                      type: "text",
                      text: `Failed to get token holders count: ${error}`,
                  },
              ],
          };
      }
  }

• index.ts:173-190 (schema)

  The ToolDefinition object defining the tool's name, description, and input schema (JSON Schema) for validation.

  const getTokenHoldersCount: ToolDefinition = {
      name: "get_token_holders_count",
      description: "Get the number of token holders for a given token address",
      inputSchema: {
          type: "object",
          properties: {
              chain_id: {
                  type: "integer",
                  description: "The chain ID",
              },
              token_address: {
                  type: "string",
                  description: "The address of the token",
              },
          },
          required: ["chain_id", "token_address"],
      },
  };

• index.ts:216-223 (registration)

  Registration of the tool in the toolDefinitions map used for MCP server capabilities.

  const toolDefinitions: { [key: string]: ToolDefinition } = {
      [getFilteredRpcList.name]: getFilteredRpcList,
      [getChainId.name]: getChainId,
      [getTotalSupply.name]: getTotalSupply,
      [getTokenBalance.name]: getTokenBalance,
      [getTokenHolders.name]: getTokenHolders,
      [getTokenHoldersCount.name]: getTokenHoldersCount
  };

• index.ts:489-490 (registration)

  Registration in the switch statement of the callToolHandler that routes the tool call to the handler function.

  case getTokenHoldersCount.name:
      return await handleGetTokenHoldersCount(req, apiKey);