Etherscan MCP Tool

Instructions

Implementation Reference

• index.ts:307-349 (handler)

  The handler function that implements the core logic of the 'get_token_holders' tool by querying the Etherscan API for the top 10 token holders and formatting the response.

  async function handleGetTokenHolders(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=tokenholderlist&contractaddress=${tokenAddress}&page=1&offset=10&apikey=${apiKey}`
          );
  
          if (response.data.status === "1") {
              const tokenHolders = response.data.result.map((holder: any) => {
                  return `${holder.TokenHolderAddress}: ${holder.TokenHolderQuantity}`;
              }).join("\n");
  
              return {
                  content: [
                      {
                          type: "text",
                          text: `Token holders for token ${tokenAddress} on chain ${chainId}: ${tokenHolders}`,
                      },
                  ],
              };
          } else {
              return {
                  content: [
                      {
                          type: "text",
                          text: `Failed to get token holders: ${response.data.message}`,
                      },
                  ],
              };
          }
      } catch (error) {
          return {
              content: [
                  {
                      type: "text",
                      text: `Failed to get token holders: ${error}`,
                  },
              ],
          };
      }
  }

• index.ts:154-171 (schema)

  The ToolDefinition object defining the schema, name, description, and input parameters for the 'get_token_holders' tool.

  const getTokenHolders: ToolDefinition = {
      name: "get_token_holders",
      description: "Get the 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:487-488 (registration)

  The switch case in the main tool handler that routes calls to 'get_token_holders' to its specific handler function.

  case getTokenHolders.name:
      return await handleGetTokenHolders(req, apiKey);

• index.ts:221-222 (registration)

  Registration of the tool definition in the toolDefinitions map used by the MCP server.

  [getTokenHolders.name]: getTokenHolders,
  [getTokenHoldersCount.name]: getTokenHoldersCount

• index.ts:509-511 (registration)

  The server capabilities section that registers all tool definitions, including 'get_token_holders', for the MCP protocol.

  capabilities: {
      tools: toolDefinitions,
  }