@mgcrea/mcp-apple-safari
MCP server for the macOS Safari browser: what you have visited, what is open now, and what is on
the page in front of you.
{
"mcpServers": {
"apple-safari": { "command": "npx", "args": ["-y", "@mgcrea/mcp-apple-safari"] }
}
}
Three lanes that are not fallbacks for each other
This is the thing to understand before anything else. Every other surface in this bundle has two
routes to the same data and the choice is about speed. Safari's lanes see almost disjoint things,
and each needs a different permission — so an ungranted Safari server is not a slower Safari server,
it is a different and much smaller one.
| Lane | Needs | Answers |
|---|
| File | Full Disk Access | the past: history, bookmarks, the Reading List |
| Apple Events | an Automation grant, Safari running | the present: which tabs are open |
| Extension | the extension enabled AND allowed on that site | the page: its text, its elements, acting on it |
The extension lane needs no TCC grant of any kind. Safari consents to it one website at a time,
which the user can see and revoke per site.
Read
| Tool | What |
|---|
apple_safari_search_history | history by text or date range, with visit counts |
apple_safari_get_page | one history item by ref |
apple_safari_list_tabs | tabs open right now, optionally enriched from history |
apple_safari_list_bookmarks | the bookmark tree |
apple_safari_list_reading_list | saved items, and which are unread |
apple_safari_read_page | a captured page as text or HTML |
apple_safari_page_elements | what is clickable or typeable on a live page |
apple_safari_wait_for | wait until some text appears on a page, or leaves it |
apple_safari_diagnostics | which lanes work, and why one does not |
Opt-in read — APPLE_SAFARI_ALLOW_CODES
| Tool | What |
|---|
apple_safari_find_codes | a one-time 2FA code in the TEXT of an open page |
Opt-in read — APPLE_SAFARI_ALLOW_NETWORK
| Tool | What |
|---|
apple_safari_network_record | arm, stop, clear or report recording on a page (reload needs writes) |
apple_safari_network_list | what the page fetched: method, URL, status, timing, no bodies |
apple_safari_network_get | one request's headers and body; saveAs writes a file (needs writes) |
Opt-in read — APPLE_SAFARI_ALLOW_COOKIES, and only for sites in APPLE_SAFARI_COOKIE_HOSTS
| Tool | What |
|---|
apple_safari_cookies | a page's cookies, HttpOnly included, as metadata; saveAs writes named ones |
Write — APPLE_SAFARI_ALLOW_WRITES
| Tool | What |
|---|
apple_safari_open_url | open a URL, in a new tab or the current |
apple_safari_add_reading_list_item | save a URL for later |
apple_safari_close_tabs | close tabs an agent opened, if unmoved |
apple_safari_click | click an element on a live page |
apple_safari_fill | type into one |
apple_safari_scroll | scroll a page |
apple_safari_submit | submit the form an element belongs to |
Configuration
| Variable | Default | |
|---|
APPLE_SAFARI_ALLOW_WRITES | off | Register the seven write tools at all. |
APPLE_SAFARI_ALLOW_CODES | off | One-time codes — see below. |
APPLE_SAFARI_ALLOW_NETWORK | off | Network capture — see below. |
APPLE_SAFARI_ALLOW_COOKIES | off | Reading cookies — see below. |
APPLE_SAFARI_COOKIE_HOSTS | empty | Sites whose cookies may be read. Empty = none. |
APPLE_SAFARI_DOWNLOAD_DIR | ~/Downloads | Where saveAs writes. |
APPLE_SAFARI_NETWORK_CHUNK_CHARS | 262144 | Characters per native message when pulling a body. |
APPLE_SAFARI_LIVE_TABS | on | Use the Apple Events lane. Off = no Apple Event. |
APPLE_SAFARI_STORE | auto | Explicit History.db path. |
APPLE_SAFARI_BOOKMARKS | auto | Explicit Bookmarks.plist path. |
APPLE_SAFARI_PAGES | auto | Explicit extension capture directory. |
APPLE_SAFARI_OPENED_TABS | auto | Explicit record of tabs open_url opened. |
APPLE_SAFARI_ACTION_TIMEOUT_MS | 12000 | How long an action waits for the page to answer. |
APPLE_SAFARI_LIVE_READ_TIMEOUT_MS | 2500 | How long read_page waits on the tab. 0 = capture. |
APPLE_SAFARI_READING_LIST_CONFIRM_MS | 1500 | Beat before re-reading to confirm a Reading List add. |
APPLE_SAFARI_INDEX_MODE | auto | auto | ro | immutable | off. |
APPLE_SAFARI_DEFAULT_RANGE_DAYS | 30 | Window when only a start is given. |
APPLE_SAFARI_MAX_RANGE_DAYS | 3660 | Hard ceiling on a single range. |
APPLE_SAFARI_MAX_RESULTS | — | Default page size. |
APPLE_SAFARI_EXPOSE_PROMPTS | off | Register prompts and cupertino:// resources. |
APPLE_SAFARI_DEBUG | off | Verbose logging. |
APPLE_SAFARI_ALLOW_CODES
Two things move together when it is on: find_codes is registered, and page_elements returns the
value of a one-time-code field. It is a read, and deliberately not folded into
ALLOW_WRITES — reaching a read through the write gate would mean granting the right to click a
button in order to see a number.
A credential field is withheld either way. A password, a card number or a CVC comes back
redacted: "credential" with no value and no setting that returns it. This flag is named for codes
and does not widen past them. In both cases hasValue still says whether the field is filled, which
is usually what you needed.
It is weaker than the Messages gate of the same name, and worth knowing which. There, off means
the tool does not exist and the alternative is sifting whole threads. Here read_page stays ungated,
so off removes the targeted field read and the live DOM scan — not every byte of a page.
See docs/passwords.md in the repo for why the Passwords app itself is unreachable by any lane, and
why reading a code a website shows is a different question from reading the vault.
APPLE_SAFARI_ALLOW_NETWORK
Registers network_record, network_list and network_get, which show what a page you have
allowed the extension on fetched: fetch and XMLHttpRequest calls from the top frame, console
errors, and resource-timing entries. It is a read gate and is not folded into ALLOW_WRITES,
for the reason ALLOW_CODES is not: the traffic of a signed-in page is session material, and that
is a different exposure from a one-time code.
- Bodies are not redacted, and neither are URLs. Headers named
authorization,
proxy-authorization, cookie or set-cookie, or containing token, secret, api-key or
apikey, come back as <redacted: N chars>. A body has no names to match, so it is returned as
the page saw it, and URLs are returned in full, query strings included, so a token in one comes
back too. Turn the gate on knowing that.
- Opt-in per tab, and it expires. Nothing is wrapped until
network_record starts, recording
survives a reload for 15 minutes by default (120 at most), and stop ends it at once.
- Two things need
ALLOW_WRITES as well: reload: true on network_record, which re-runs the
page, and saveAs on network_get, which writes into APPLE_SAFARI_DOWNLOAD_DIR (a bare
filename, and never over an existing file unless overwrite: true). Each fails with an error
naming APPLE_SAFARI_ALLOW_WRITES.
- What it cannot see: subframes, web and service workers,
<img>/<script> bodies and
WebSockets. Request ids die when the page reloads or navigates. On a page whose
Content-Security-Policy refuses inline scripts there is a fallback that loads the recorder by URL
instead. It has not been verified in Safari; if it works it arrives late, so the page's first
requests can be missing, and if it does not, hook.injection says "blocked".
- A file inside an API response:
network_get with jsonPath to the field, decode: "base64"
and saveAs. The bytes go to disk, not into the conversation.
APPLE_SAFARI_ALLOW_COOKIES and APPLE_SAFARI_COOKIE_HOSTS
Registers cookies, which lists the cookies Safari would send to an open page, HttpOnly ones
included, so a signed-in session can be handed to a local tool without copying it out of Safari by
hand. It reads through browser.cookies in the extension's background worker, so the values never
enter the page's own process.
- Gated twice. The flag decides whether the tool exists;
APPLE_SAFARI_COOKIE_HOSTS decides
which sites it may read. A login cookie is the login, so the flag alone would hand any agent any
session in the browser. The list is comma-separated registrable domains (yahoo.com), each
covering the domain and its subdomains on a label boundary (never notyahoo.com). Empty, the
default, refuses every page, and a refusal names the setting. An entry with no dot is ignored;
there is no public-suffix list, so do not list one like co.uk.
- No value inline, ever. The result gives each cookie's name, domain, path,
secure,
httpOnly, sameSite and expires (null for a session cookie).
- To get values out:
names plus saveAs writes the named cookies into
APPLE_SAFARI_DOWNLOAD_DIR as one Cookie header value — A3=…; T=…; Y=…, with no Cookie:
prefix and no trailing newline, so a tool that takes a cookie string reads the file as is — mode 0600. A bare filename, never over an existing file unless overwrite: true, and it needs
ALLOW_WRITES. A name the page lacks writes nothing and says which.
- The extension asks for the
cookies permission. On the install measured, Safari did not ask
for approval again and the API worked at once; if yours shows the extension switched off, enable it
in Safari › Settings › Extensions, and until then the tool says browser.cookies is not
available. It still reads only on sites you have allowed the extension on: there is no new
all-sites grant.
- In the Cupertino app both are one control: Safari › Read cookies, with the sites in the
Sites field under it, passed only while the box is ticked. Started yourself, the server needs
both variables set and Full Disk Access, so it can reach the extension's container.
Buffer limits: 1,000 records and 50 MiB of bodies per page; bodies are kept up to maxBodyBytes
(10 MiB by default, 50 MiB at most). See docs/safari.md.
Notes that will bite you
- An unmatched tab is normal, not an error. The only join key between a live tab and history is
the URL, and it is trivially lossy: measured match rates were 60.7%, 55.3% and 8.3% across
three runs. A single-page app reached by
pushState commits no history row at all, so the page
was genuinely visited and genuinely is not in the store. Treat history: null as NOT FOUND, never
as "never visited".
- An exact URL match is not proof the row is about that page. One measured tab on
http://localhost:4321/ matched a history row for an entirely different project. Any local
address carries this.
read_page is live when the tab can answer, and a snapshot when it cannot. It asks the open
tab first and waits APPLE_SAFARI_LIVE_READ_TIMEOUT_MS; a visible tab answers within a second. A
hidden tab checks in only every ten, so it — like a closed one — gets the capture the extension
stored at load and as the page settled, with source: "capture", ageSeconds, and liveRead
saying why. The acting tools always go to the live page, which is why they cost about a second on
a visible tab and up to ten on a hidden one.
- Read a form with
page_elements, not read_page. Field values are not page text. Elements
carry value (a select's shown option too), checked on checkboxes and radios, and
disabled: true on greyed-out controls, which are listed rather than dropped. Values are cut at
200 characters unless maxValueChars raises it, and a cut one says so with valueTruncated.
- Set a form with
fill and click. fill writes through the element's native setter, which
is what makes React register the change — a plain el.value = shows the text and leaves React's
state on the old value. On a select it takes the option text page_elements reports. Checkboxes
and radios are clicked, not filled, and a click toggles, so read checked first. File inputs
cannot be set: a content script has no way to reach a file on disk.
- A timeout from an action means nothing was listening — the extension off, not allowed on that
site, or the page closed. It never means the page refused. Commands are at-most-once: one that is
handed out and lost is not retried, because a click that MIGHT have landed must not be repeated.
- Element ids die on navigation. They come from a
page_elements call and are valid for that
page only. Never construct one, and re-enumerate after any click that loaded something.
- A Reading List add hits the network. Safari fetches the URL in the background to build the
entry, and overwrites any
withTitle you pass with the page's own title. verified has three
states and is never false: the file lags the add by about 2 s, and reporting an unconfirmed
write as a failed one makes callers retry — into a list with no remove verb.
- The write lane needs no Full Disk Access. Both Apple Events writes work on a machine where the
read lane does not.
APPLE_SAFARI_LIVE_TABS=false outranks the write gate, because that flag
promises a server that sends no Apple Event at all.
open_url accepts http and https only. A javascript: URL would be do JavaScript
through the front door — measured: Safari accepts one through the navigation verb — and file:
is a navigation verb that reads local files.
Licence
MIT.