# extension_element

> Click, fill, read or wait for one element by CSS selector, or send trusted mouse and key input in an open surface, a page by url or a targetId.

Canonical: https://docs.extension.dev/tools/mcp/element
This page as Markdown: https://docs.extension.dev/tools/mcp/element.md
Section: MCP tool reference
Siblings: [extension_add_feature](https://docs.extension.dev/tools/mcp/add-feature.md) · [extension_analyze](https://docs.extension.dev/tools/mcp/analyze.md) · [extension_approvals](https://docs.extension.dev/tools/mcp/approvals.md) · [extension_assert](https://docs.extension.dev/tools/mcp/assert.md) · [extension_auth](https://docs.extension.dev/tools/mcp/auth.md) · [extension_browsers](https://docs.extension.dev/tools/mcp/browsers.md) · [extension_build](https://docs.extension.dev/tools/mcp/build.md) · [extension_builds](https://docs.extension.dev/tools/mcp/builds.md) · [extension_builds_act](https://docs.extension.dev/tools/mcp/builds-act.md) · [extension_create](https://docs.extension.dev/tools/mcp/create.md) · [extension_dev](https://docs.extension.dev/tools/mcp/dev.md) · [extension_docs_search](https://docs.extension.dev/tools/mcp/docs-search.md) · [extension_doctor](https://docs.extension.dev/tools/mcp/doctor.md) · [extension_dom_snapshot](https://docs.extension.dev/tools/mcp/dom-snapshot.md) · [extension_eval](https://docs.extension.dev/tools/mcp/eval.md) · [extension_inspect](https://docs.extension.dev/tools/mcp/inspect.md) · [extension_list_extensions](https://docs.extension.dev/tools/mcp/list-extensions.md) · [extension_logs](https://docs.extension.dev/tools/mcp/logs.md) · [extension_manifest_validate](https://docs.extension.dev/tools/mcp/manifest-validate.md) · [extension_network](https://docs.extension.dev/tools/mcp/network.md) · [extension_open](https://docs.extension.dev/tools/mcp/open.md) · [extension_preview_web](https://docs.extension.dev/tools/mcp/preview-web.md) · [extension_project_create](https://docs.extension.dev/tools/mcp/project-create.md) · [extension_publish](https://docs.extension.dev/tools/mcp/publish.md) · [extension_release_promote](https://docs.extension.dev/tools/mcp/release-promote.md) · [extension_release_status](https://docs.extension.dev/tools/mcp/release-status.md) · [extension_reload](https://docs.extension.dev/tools/mcp/reload.md) · [extension_screenshot](https://docs.extension.dev/tools/mcp/screenshot.md) · [extension_shares](https://docs.extension.dev/tools/mcp/shares.md) · [extension_start](https://docs.extension.dev/tools/mcp/start.md) · [extension_stop](https://docs.extension.dev/tools/mcp/stop.md) · [extension_storage](https://docs.extension.dev/tools/mcp/storage.md) · [extension_submit](https://docs.extension.dev/tools/mcp/submit.md) · [extension_submit_check](https://docs.extension.dev/tools/mcp/submit-check.md) · [extension_templates](https://docs.extension.dev/tools/mcp/templates.md) · [extension_theme_verify](https://docs.extension.dev/tools/mcp/theme-verify.md) · [extension_try](https://docs.extension.dev/tools/mcp/try.md) · [extension_wait](https://docs.extension.dev/tools/mcp/wait.md) · [extension_workspace](https://docs.extension.dev/tools/mcp/workspace.md) · [extension_workspace_create](https://docs.extension.dev/tools/mcp/workspace-create.md) · [Install in your client](https://docs.extension.dev/tools/mcp/clients.md)
Map of every page: https://docs.extension.dev/llms.txt · Whole corpus: https://docs.extension.dev/llms-full.txt

---

# `extension_element`

Click, fill, read or wait for one element by CSS selector, or send trusted mouse and key input in an open surface, a page by url or a targetId.

## Quick start

> Click the Save button in the popup, then read the status line


## How the agent uses it

Runs no caller code, so no allowEval; Chromium only.

## Page text in the answer

Part of this tool's answer is text a web page or the extension wrote. The server fences it between `<untrusted-data-ID>` and `</untrusted-data-ID>` with a fresh random `ID` per call, named in `untrusted.boundary`. A fence is a signal to the model, not a gate: pair it with `--no-ship` when the agent reads pages you do not trust. See [Server flags and telemetry](/tools/mcp/flags).

## Reference

| | |
| --- | --- |
| Group | local, on by default |
| Tier | Act |
| Needs | a live Chromium dev or start session with its debug port; no allowEval |
| Read only | no |
| Destructive | no |
| Idempotent | no |
| Reaches the open web | no |

### Inputs

| Input | Type | Required | Default | What it does |
| --- | --- | --- | --- | --- |
| `projectPath` | string | yes |  | Project root of a running session: extension_dev, extension_start, or `npx extension dev\|start` by hand |
| `action` | "click" \| "fill" \| "text" \| "wait" \| "move" \| "press" \| "release" \| "type" \| "key" \| "scroll" | yes |  | click (a real mouse press), fill, text, wait (until visible); move, press, release, type, key, scroll send trusted input. |
| `selector` | string | no |  | CSS selector matching exactly one element (the point for input actions; focused before type and key). |
| `value` | string | no |  | fill: the value to set. |
| `x` | number | no |  | press, release, scroll: the point's x in CSS pixels of the viewport, when no selector. |
| `y` | number | no |  | The point's y, with x. |
| `points` | array of object | no |  | move: the path, one trusted mousemove per point; a selector's center goes first. |
| `button` | "left" \| "middle" \| "right" | no |  | press, release: the mouse button (default left). |
| `text` | string | no |  | type: the characters, one key down and up each; a newline is Enter. |
| `key` | string | no |  | key: a key name (Enter, Escape, Tab, ArrowDown, F5) or one character. |
| `modifiers` | array of "Alt" \| "Control" \| "Meta" \| "Shift" | no |  | Modifiers held during the input. |
| `deltaX` | number | no |  | scroll: wheel delta in CSS pixels (positive scrolls right). |
| `deltaY` | number | no |  | scroll: wheel delta in CSS pixels (positive scrolls down). |
| `context` | "popup" \| "options" \| "sidebar" \| "devtools" \| "newtab" \| "history" \| "bookmarks" | no |  | An open surface (extension_open first). |
| `url` | string | no |  | A web page's tab by url. |
| `targetId` | string | no |  | targetId from extension_open or dom_snapshot listTargets; overrides url. |
| `browser` | string | no |  | Session browser; required when several run. |
| `timeout` | number | no |  | Timeout ms; wait polls until it (default 10000, max 30000). |

## When it fails

- **The call is refused because no session is live.** Start one with [`extension_dev`](/tools/mcp/dev) or [`extension_start`](/tools/mcp/start) and call again.
- **Eval is refused.** Eval is the one gate that stays off. Start the session with `allowEval: true` on [`extension_dev`](/tools/mcp/dev).

## Next

- [MCP server](/tools/mcp): install, the three groups and the session gates
- [Install in your client](/tools/mcp/clients)
- [`extension_eval`](/tools/mcp/eval): Evaluate JavaScript in a running extension's background, surface, content script, page or targetId.
- [`extension_open`](/tools/mcp/open): Open an extension surface or a url, or replay the toolbar action, a context menu item or a shortcut, over the control channel (by hand: --allow-control).
- [`extension_reload`](/tools/mcp/reload): Reload a live session's background, or one tab, over the control channel (allowControl) when hot reload missed an edit; answers once it is back.
- [`extension_storage`](/tools/mcp/storage): Read or write one chrome.storage key from the background, over the control channel.
