Puppeteer MCP Server

Instructions

Implementation Reference

• index.ts:333-382 (handler)

  Handler for puppeteer_evaluate tool: executes the provided JavaScript script in the browser page context, overrides console methods to capture logs, returns execution result and console output.

  case "puppeteer_evaluate":
    try {
      await page.evaluate(() => {
        window.mcpHelper = {
          logs: [],
          originalConsole: { ...console },
        };
  
        ["log", "info", "warn", "error"].forEach((method) => {
          (console as any)[method] = (...args: any[]) => {
            window.mcpHelper.logs.push(`[${method}] ${args.join(" ")}`);
            (window.mcpHelper.originalConsole as any)[method](...args);
          };
        });
      });
  
      const result = await page.evaluate(args.script);
  
      const logs = await page.evaluate(() => {
        Object.assign(console, window.mcpHelper.originalConsole);
        const logs = window.mcpHelper.logs;
        delete (window as any).mcpHelper;
        return logs;
      });
  
      return {
        content: [
          {
            type: "text",
            text: `Execution result:\n${JSON.stringify(
              result,
              null,
              2
            )}\n\nConsole output:\n${logs.join("\n")}`,
          },
        ],
        isError: false,
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Script execution failed: ${(error as Error).message}`,
          },
        ],
        isError: true,
      };
    }

• index.ts:111-121 (schema)

  Schema definition for puppeteer_evaluate tool, specifying input as a JavaScript script string.

  {
    name: "puppeteer_evaluate",
    description: "Execute JavaScript in the browser console",
    inputSchema: {
      type: "object",
      properties: {
        script: { type: "string", description: "JavaScript code to execute" },
      },
      required: ["script"],
    },
  },

• index.ts:18-122 (registration)

  Registration of puppeteer_evaluate in the TOOLS array used for listing available tools.

  const TOOLS: Tool[] = [
    {
      name: "puppeteer_navigate",
      description: "Navigate to a URL",
      inputSchema: {
        type: "object",
        properties: {
          url: { type: "string" },
        },
        required: ["url"],
      },
    },
    {
      name: "puppeteer_screenshot",
      description: "Take a screenshot of the current page or a specific element",
      inputSchema: {
        type: "object",
        properties: {
          name: { type: "string", description: "Name for the screenshot" },
          selector: {
            type: "string",
            description: "CSS selector for element to screenshot",
          },
          width: {
            type: "number",
            description: "Width in pixels (default: 800)",
          },
          height: {
            type: "number",
            description: "Height in pixels (default: 600)",
          },
        },
        required: ["name"],
      },
    },
    {
      name: "puppeteer_click",
      description: "Click an element on the page",
      inputSchema: {
        type: "object",
        properties: {
          selector: {
            type: "string",
            description: "CSS selector for element to click",
          },
        },
        required: ["selector"],
      },
    },
    {
      name: "puppeteer_fill",
      description: "Fill out an input field",
      inputSchema: {
        type: "object",
        properties: {
          selector: {
            type: "string",
            description: "CSS selector for input field",
          },
          value: { type: "string", description: "Value to fill" },
        },
        required: ["selector", "value"],
      },
    },
    {
      name: "puppeteer_select",
      description: "Select an element on the page with Select tag",
      inputSchema: {
        type: "object",
        properties: {
          selector: {
            type: "string",
            description: "CSS selector for element to select",
          },
          value: { type: "string", description: "Value to select" },
        },
        required: ["selector", "value"],
      },
    },
    {
      name: "puppeteer_hover",
      description: "Hover an element on the page",
      inputSchema: {
        type: "object",
        properties: {
          selector: {
            type: "string",
            description: "CSS selector for element to hover",
          },
        },
        required: ["selector"],
      },
    },
    {
      name: "puppeteer_evaluate",
      description: "Execute JavaScript in the browser console",
      inputSchema: {
        type: "object",
        properties: {
          script: { type: "string", description: "JavaScript code to execute" },
        },
        required: ["script"],
      },
    },
  ];

• index.ts:463-465 (registration)

  Registration of the call tool handler which dispatches to puppeteer_evaluate case based on name.

  server.setRequestHandler(CallToolRequestSchema, async (request) =>
    handleToolCall(request.params.name, request.params.arguments ?? {})
  );

• index.ts:459-461 (registration)

  Registration of list tools handler which includes puppeteer_evaluate from TOOLS.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: TOOLS,
  }));