click_element
Click buttons, links, or interactive elements on web pages using CSS selectors or visible text. Automatically waits for page updates after clicking to navigate interfaces, open modals, or trigger UI actions.
Instructions
Click a button, link, or any interactive element on the page. Useful for navigating through multi-step interfaces, opening chat modals, starting new conversations, or triggering UI actions. Can target elements by CSS selector or by their visible text content. Automatically waits after clicking to allow page updates.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | Session ID obtained from initialize_session | |
| selector | No | CSS selector for the element to click (e.g., 'button#start-chat', '.new-conversation-btn'). Use this when you know the exact selector. | |
| text | No | Alternative to selector: visible text content to search for and click (e.g., 'Start Chat', 'Sign In', 'New Conversation'). Use this when selector is unknown. | |
| waitAfter | No | Milliseconds to wait after clicking to allow animations, redirects, or dynamic content to load (default: 1000) |
Implementation Reference
- src/tools/interaction.js:11-59 (handler)Core implementation of the clickElement function. Handles clicking elements by CSS selector or visible text content using Playwright's page.click or evaluate-based text search. Includes error handling and returns success status with current page info.export async function clickElement( sessionId, selector = null, text = null, waitAfter = 1000 ) { const session = getSession(sessionId); const { page } = session; try { if (selector) { await page.click(selector); } else if (text) { // Try to find element by text content const clickedByText = await page.evaluate((searchText) => { const elements = Array.from( document.querySelectorAll('button, a, [role="button"], [onclick]') ); const target = elements.find((el) => el.textContent.trim().toLowerCase().includes(searchText.toLowerCase()) ); if (target) { target.click(); return true; } return false; }, text); if (!clickedByText) { // Try using Playwright's text selector await page.click(`text=${text}`); } } else { throw new Error("Either selector or text parameter is required"); } await page.waitForTimeout(waitAfter); return { success: true, sessionId, currentUrl: page.url(), title: await page.title(), message: `Clicked element successfully`, }; } catch (error) { throw new Error(`Failed to click element: ${error.message}`); } }
- src/index.js:126-155 (schema)MCP tool schema definition for 'click_element', including name, description, and detailed inputSchema with properties for sessionId, selector, text, waitAfter, and required fields.name: "click_element", description: "Click a button, link, or any interactive element on the page. Useful for navigating through multi-step interfaces, opening chat modals, starting new conversations, or triggering UI actions. Can target elements by CSS selector or by their visible text content. Automatically waits after clicking to allow page updates.", inputSchema: { type: "object", properties: { sessionId: { type: "string", description: "Session ID obtained from initialize_session", }, selector: { type: "string", description: "CSS selector for the element to click (e.g., 'button#start-chat', '.new-conversation-btn'). Use this when you know the exact selector.", }, text: { type: "string", description: "Alternative to selector: visible text content to search for and click (e.g., 'Start Chat', 'Sign In', 'New Conversation'). Use this when selector is unknown.", }, waitAfter: { type: "number", description: "Milliseconds to wait after clicking to allow animations, redirects, or dynamic content to load (default: 1000)", default: 1000, }, }, required: ["sessionId"], }, },
- src/index.js:441-457 (registration)Tool dispatch/registration in the central CallToolRequestSchema handler. Matches 'click_element' tool name, validates parameters, and invokes the clickElement implementation.case "click_element": { const { sessionId, selector, text, waitAfter = 1000 } = args; if (!sessionId) { throw new McpError( ErrorCode.InvalidParams, "sessionId parameter is required" ); } if (!selector && !text) { throw new McpError( ErrorCode.InvalidParams, "Either selector or text parameter is required" ); } result = await clickElement(sessionId, selector, text, waitAfter); break; }