playwright_upload_file

Upload files to web forms using Playwright automation. Specify a CSS selector for the file input element and provide either a local file path or a resource URI to handle file uploads in browser automation workflows.

Instructions

Upload a file to an input[type='file'] element on the page. In HTTP mode (disabled), provide an uploadResourceUri from construct_upload_url (preferred) or a reachable filePath.

Input Schema

TableJSON Schema

Name	Required	Description
`selector`	Yes	CSS selector for the file input element
`filePath`	No	Absolute path to the file to upload (stdio mode only; ignored in HTTP mode)
`uploadResourceUri`	No	Resource URI returned from the upload endpoint (HTTP mode)

Implementation Reference

src/tools/browser/interaction.ts:210-230 (handler)

Execution handler for the playwright_upload_file tool. Prepares the file path and uses Playwright's setInputFiles to upload to the specified selector.

async execute(args: any, context: ToolContext): Promise<ToolResponse> {
  return this.safeExecute(context, async (page) => {
    if (!args.selector) {
      return createErrorResponse("Selector is required to upload a file");
    }

    const prepared = await this.prepareUploadFile(args, context.server, context);
    if ("error" in prepared) {
      return createErrorResponse(prepared.error);
    }

    const { path: uploadPath, cleanup, displayName } = prepared;
    try {
      await page.waitForSelector(args.selector);
      await page.setInputFiles(args.selector, uploadPath);
      return createSuccessResponse(`Uploaded file '${displayName}' to '${args.selector}'`);
    } finally {
      await cleanup().catch(() => {});
    }
  });
}

src/tools/browser/interaction.ts:147-205 (helper)

Helper method to resolve file path from either local filePath (stdio mode) or uploadResourceUri (HTTP mode) using upload manager.

private async prepareUploadFile(
  args: any,
  server: any,
  _context: ToolContext,
): Promise<{ path: string; cleanup: () => Promise<void>; displayName: string } | { error: string }> {
  const sessionId = getSessionIdForServer(server);
  const uploadResourceUri = args.uploadResourceUri ?? args.fileResourceUri;
  const inHttpMode = Boolean(sessionId);

  if (uploadResourceUri) {
    const parsed = parseUploadResourceUri(uploadResourceUri);
    const targetSession = parsed?.sessionId ?? sessionId;
    if (!parsed || !targetSession) {
      return { error: "Invalid upload resource URI" };
    }
    const meta = await resolveUploadResource({
      resourceUri: uploadResourceUri,
      sessionId: targetSession,
    });
    if (!meta) {
      return { error: "Uploaded file could not be resolved for this session" };
    }
    const cleanup = async () => {};
    return { path: meta.filePath, cleanup, displayName: meta.name };
  }

  if (args.filePath) {
    const resolvedPath = path.resolve(args.filePath);
    try {
      await fs.access(resolvedPath);
      return {
        path: resolvedPath,
        cleanup: async () => {},
        displayName: args.filePath,
      };
    } catch {
      if (inHttpMode) {
        return {
          error: `File not found at path: ${resolvedPath}. In HTTP mode, first call construct_upload_url, upload the file, then call playwright_upload_file with uploadResourceUri.`,
        };
      }
      return { error: `File not found at path: ${resolvedPath}` };
    }
  }

  if (inHttpMode) {
    const uploadUrl = getUploadEndpointUrl();
    const hint = uploadUrl
      ? ` Call construct_upload_url to obtain the upload endpoint for this session (e.g., ${uploadUrl}/<sessionId>).`
      : "";
    return {
      error: `No file provided. In HTTP mode, first upload a file and provide uploadResourceUri.${hint}`,
    };
  }

  return {
    error: "filePath is required in stdio mode.",
  };
}

src/tools.ts:194-212 (schema)

Input schema and description definition for the playwright_upload_file tool.

{
  name: "playwright_upload_file",
  description: `Upload a file to an input[type='file'] element on the page. In HTTP mode (${httpMode ? "enabled" : "disabled"}), provide an uploadResourceUri from construct_upload_url (preferred) or a reachable filePath.`,
  inputSchema: {
    type: "object",
    properties: {
      selector: { type: "string", description: "CSS selector for the file input element" },
      filePath: {
        type: "string",
        description: "Absolute path to the file to upload (stdio mode only; ignored in HTTP mode)",
      },
      uploadResourceUri: {
        type: "string",
        description: "Resource URI returned from the upload endpoint (HTTP mode)",
      },
    },
    required: ["selector"],
  },
},

src/toolHandler.ts:603-604 (registration)
Dispatch registration in handleToolCall switch statement routing to UploadFileTool.
```
case "playwright_upload_file":
  return await uploadFileTool.execute(args, context);
```
src/toolHandler.ts:398-398 (registration)
Instantiation of UploadFileTool instance in initializeTools function.
```
if (!uploadFileTool) uploadFileTool = new UploadFileTool(server);
```

mcp-playwright