Cookies & storage¶

Cookie jar and localStorage helpers let you read, set, and clear browser storage across origins. Set and clear operations affect the instance's stored state immediately.

Examples below focus on tool-specific data. Registered tools also return the shared operation metadata and error fields.

For localStorage calls with an explicit origin, the browser compares its canonical origin with the requested URL's canonical origin in the same JavaScript turn that accesses storage. Equivalent IDN/punycode hosts, IPv6 spellings, shortened IPv4 addresses, and default ports therefore work consistently. A redirect to a different scheme, host, or effective port returns invalid_params before the tool reads or changes that destination's storage. The response echoes the requested origin spelling.

Operation metadata identifies the temporary page that accesses storage, while the selected active page remains unchanged. Cleanup attempts to close the temporary page within a bounded, shielded period, including after cancellation. A cleanup failure is reported if the storage operation otherwise succeeded; if an earlier error or cancellation occurred, that original result is preserved and the cleanup failure is logged. Inspect tabs after a failure if cleanup could not finish.

Optional page_id selects a live page without changing the selected tab; an invalid explicit target returns page_not_found. Frame-capable calls also accept frame_id and return frame_not_found for a detached or foreign frame. Omitted targets retain existing behavior. See explicit targeting.

browser_get_cookies¶

Return cookies stored in the instance, optionally filtered by URL and name.

Signature

async def browser_get_cookies(
    instance: str,
    urls: list[str] | None = None,
    name: str | None = None,
) -> dict[str, Any]

Parameters

Name	Type	Default	Description
`instance`	`str`	—	Instance name.
`urls`	`list[str] \\| None`	`None`	List of full URLs to filter cookies by domain/path rules. `None` returns all cookies.
`name`	`str \\| None`	`None`	Exact cookie name to filter by (applied after URL filtering).

Returns — see response envelope. data shape:

{
  "cookies": [
    {
      "name": "sessionid",
      "value": "abc123",
      "domain": ".example.com",
      "path": "/",
      "expires": 1735689600,
      "httpOnly": true,
      "secure": true,
      "sameSite": "Strict"
    }
  ]
}

Errors — emits error_type codes (see envelope error codes):

instance_not_found

Example

Request:

{
  "name": "browser_get_cookies",
  "arguments": { "instance": "main", "urls": ["https://example.com"] }
}

Response:

{
  "status": "success",
  "instance": "main",
  "data": {
    "cookies": [
      {
        "name": "sessionid",
        "value": "abc123",
        "domain": ".example.com",
        "path": "/",
        "expires": 1735689600,
        "httpOnly": true,
        "secure": true,
        "sameSite": "Strict"
      }
    ]
  }
}

Notes — When both urls and name are provided, filtering is applied in order: URLs first, then exact name match. When name is given but no cookies match, the result is an empty list (not an error). Cookies applicable to the given URLs are determined by matching domain and path rules per the cookie RFC.

browser_set_cookies¶

Add or update cookies on the instance using Playwright cookie format.

Signature

async def browser_set_cookies(
    instance: str, cookies: list[dict[str, Any]], *, page_id: str | None = None
) -> dict[str, Any]

Parameters

Name	Type	Default	Description
`instance`	`str`	—	Instance name.
`cookies`	`list[dict[str, Any]]`	—	List of cookie dicts. Each must have at minimum `name` and `value`. Must also include either (`domain` + `path`) or `url`. Optional fields: `path` (default `"/"`), `expires` (Unix timestamp), `httpOnly`, `secure`, `sameSite` (`"Strict"`, `"Lax"`, `"None"`).
`page_id`	`str \\| None`	`None`	Stable page ID; omitted uses the selected page. Explicit targeting preserves selection and rejects unavailable IDs.

Returns — see response envelope. data shape:

{ "set_count": 2 }

Errors — emits error_type codes (see envelope error codes):

instance_not_found
invalid_params — cookie has neither domain nor url and no active page exists to default from

Example

Request:

{
  "name": "browser_set_cookies",
  "arguments": {
    "instance": "main",
    "cookies": [
      {
        "name": "sessionid",
        "value": "xyz789",
        "domain": ".example.com",
        "path": "/",
        "httpOnly": true,
        "secure": true,
        "sameSite": "Strict"
      }
    ]
  }
}

Response:

{ "status": "success", "instance": "main", "data": { "set_count": 1 } }

Notes — When a cookie has neither domain nor url, the active page's hostname is used as the default domain (if a page exists). Cookies set here take effect immediately on all pages in the instance.

browser_clear_cookies¶

Remove all cookies from the instance across all domains.

Signature

async def browser_clear_cookies(instance: str) -> dict[str, Any]

Parameters

Name	Type	Default	Description
`instance`	`str`	—	Instance name.

Returns — see response envelope. data shape:

{ "cleared": true }

Errors — emits error_type codes (see envelope error codes):

instance_not_found

Example

Request:

{ "name": "browser_clear_cookies", "arguments": { "instance": "main" } }

Response:

{ "status": "success", "instance": "main", "data": { "cleared": true } }

Notes — All cookies across all domains in the instance are deleted immediately. Pages currently loaded in the instance are not reloaded — the deletion takes effect on the next HTTP request that would send cookies.

browser_get_local_storage¶

Read localStorage for the given origin.

Signature

async def browser_get_local_storage(
    instance: str,
    origin: str,
    key: str | None = None,
) -> dict[str, Any]

Parameters

Name	Type	Default	Description
`instance`	`str`	—	Instance name.
`origin`	`str`	—	Fully-qualified URL including scheme (e.g. `"https://example.com"`).
`key`	`str \\| None`	`None`	Specific key to read. `None` returns all items.

Returns — see response envelope. data shape when key is None:

{ "items": { "theme": "dark", "user_id": "42" }, "origin": "https://example.com" }

Data shape when key is provided:

{ "key": "theme", "value": "dark", "origin": "https://example.com" }

If the key does not exist, value is null:

{ "key": "nonexistent", "value": null, "origin": "https://example.com" }

Errors — emits error_type codes (see envelope error codes):

instance_not_found
invalid_params — navigation redirected to a different origin
modal_state_blocked — a dialog or file chooser is pending
internal_error — navigation to origin failed (e.g. network error)

Example

Request (all items):

{
  "name": "browser_get_local_storage",
  "arguments": { "instance": "main", "origin": "https://example.com" }
}

Response:

{
  "status": "success",
  "instance": "main",
  "data": { "items": { "theme": "dark", "user_id": "42" }, "origin": "https://example.com" }
}

Request (specific key):

{
  "name": "browser_get_local_storage",
  "arguments": { "instance": "main", "origin": "https://example.com", "key": "theme" }
}

Response:

{
  "status": "success",
  "instance": "main",
  "data": { "key": "theme", "value": "dark", "origin": "https://example.com" }
}

Notes — Opens a temporary page that navigates to the origin, reads localStorage, then closes the page — the instance's active page is not disturbed. origin must be a fully-qualified URL including scheme; partial URLs or paths are not accepted.

Storage is accessed after the document commits, without waiting for DOMContentLoaded or site initialization scripts.

All stored keys are preserved in a full dump, including __proto__. Missing individual keys return null; an empty store returns an empty items object.

browser_set_local_storage¶

Set localStorage key-value pairs for the given origin.

Signature

async def browser_set_local_storage(instance: str, origin: str, items: dict[str, str]) -> dict[str, Any]

Parameters

Name	Type	Default	Description
`instance`	`str`	—	Instance name.
`origin`	`str`	—	Fully-qualified URL including scheme (e.g. `"https://example.com"`).
`items`	`dict[str, str]`	—	Key-value pairs to set. All values must be strings.

Returns — see response envelope. data shape:

{ "set_count": 2, "origin": "https://example.com" }

Errors — emits error_type codes (see envelope error codes):

instance_not_found
invalid_params — navigation redirected to a different origin
modal_state_blocked — a dialog or file chooser is pending
internal_error — navigation to origin failed

Example

Request:

{
  "name": "browser_set_local_storage",
  "arguments": {
    "instance": "main",
    "origin": "https://example.com",
    "items": { "theme": "dark", "user_id": "42" }
  }
}

Response:

{
  "status": "success",
  "instance": "main",
  "data": { "set_count": 2, "origin": "https://example.com" }
}

Notes — Opens a temporary page that navigates to the origin, sets each item via localStorage.setItem, then closes the page — the instance's active page is not disturbed. All values must be strings because localStorage only stores strings.

Keys such as __proto__ are written as ordinary storage keys and round-trip through browser_get_local_storage without being dropped.

Storage is accessed after the document commits, without waiting for DOMContentLoaded or site initialization scripts.

browser_clear_local_storage¶

Clear localStorage entries for an origin or for the currently active page.

Signature

async def browser_clear_local_storage(
    instance: str,
    origin: str | None = None,
    *,
    page_id: str | None = None,
) -> dict[str, Any]

Parameters

Name	Type	Default	Description
`instance`	`str`	—	Instance name.
`origin`	`str \\| None`	`None`	Fully-qualified URL including scheme to clear. When omitted, clears localStorage on the currently active page directly.
`page_id`	`str \\| None`	`None`	Stable page ID; omitted uses the selected page. Explicit targeting preserves selection and rejects unavailable IDs.

Returns — see response envelope. data shape:

{ "cleared": true, "origin": "https://example.com" }

Errors — emits error_type codes (see envelope error codes):

instance_not_found
invalid_params — navigation redirected to a different origin
modal_state_blocked — a dialog or file chooser is pending
internal_error — navigation to origin failed

Example

Request (with origin):

{
  "name": "browser_clear_local_storage",
  "arguments": { "instance": "main", "origin": "https://example.com" }
}

Response:

{
  "status": "success",
  "instance": "main",
  "data": { "cleared": true, "origin": "https://example.com" }
}

Request (active page shortcut):

{ "name": "browser_clear_local_storage", "arguments": { "instance": "main" } }

Response:

{
  "status": "success",
  "instance": "main",
  "data": { "cleared": true, "origin": "https://example.com/page" }
}

Notes — When origin is provided, a temporary page navigates to that origin, clears localStorage, then closes — the instance's active page is not disturbed. When origin is omitted, localStorage is cleared on the active page directly with no navigation (a shortcut for when you are already on the origin whose storage you want to clear). The response's origin field echoes the supplied URL, or the active page's full URL when no origin was supplied.

For an explicit origin, storage is accessed after the document commits, without waiting for DOMContentLoaded or site initialization scripts.

For browser_clear_local_storage, supplying both origin and page_id returns invalid_params. Origin-explicit storage operations retain their temporary-page behavior. browser_set_cookies validates an explicit page even when cookies already provide their own URL/domain; the page supplies an inferred domain only when needed.

Temporary origin-storage pages await automatic header setup before their first navigation. Setup failure prevents navigation/storage access and still closes the temporary page.