{
"markdown": "# arc-control-mcp\n\n[](https://github.com/DB-25/arc-control-mcp/actions/workflows/ci.yml)\n[](https://www.npmjs.com/package/arc-control-mcp)\n[](https://www.npmjs.com/package/arc-control-mcp)\n[](LICENSE)\n[](package.json)\n\nAn MCP server that drives the Arc browser on macOS: tabs, navigation, page\nreading, DOM interaction and scripting.\n\nIt exists because the bundled \"Control Chrome\" MCP server cannot be pointed at\nArc. Arc's scripting dictionary looks like Chrome's, and differs in exactly the\nplaces that matter.\n\n**Who it is for:** anyone running an agent (Claude Code or another MCP client)\non a Mac who wants it to work in Arc, the browser they are already signed in to,\ninstead of a fresh automation profile. It reads pages, fills forms, clicks\nthings, runs JavaScript, and keeps its own tabs separate from yours.\n\n**What it is not:** a cross-platform or cross-browser tool. It drives one\nbrowser on one operating system through Apple Events. There is no screenshot\ntool, no CDP, and no headless mode. There is also no Docker image, and there\ncannot be one: Apple Events do not cross a container boundary, so a container\nhas no way to reach the Arc running on your Mac. This is a 0.3.0 personal\nproject, and the [known limitations](#known-arc-limitations) below are real.\n\n## Requirements\n\n- macOS\n- [Arc](https://arc.net/) installed\n- Node 20 or newer\n\nOne runtime dependency, `@modelcontextprotocol/sdk`. No build step.\n\n## Install\n\nNothing to clone. Any MCP client can start the server with `npx`, and `@latest`\nis also how it upgrades: the next start picks up a new release.\n\n```json\n{\n \"mcpServers\": {\n \"arc\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"arc-control-mcp@latest\"]\n }\n }\n}\n```\n\n> [!IMPORTANT]\n> That config is not sufficient on its own. Two macOS permissions still have to\n> be granted, one of them in Arc's own settings where nothing will prompt you\n> for it. Until both are granted, the server starts normally and then every\n> tool fails. This is by far the most likely reason a fresh install looks\n> broken: read\n> [the two macOS permissions](#the-two-macos-permissions), the next section.\n\n`package.json` declares `\"os\": [\"darwin\"]`, so on Linux or Windows the install\nstops with `EBADPLATFORM` instead of succeeding and then failing at the first\nApple Event. Environment variables go in an `env` object alongside `args`; see\n[environment variables](#environment-variables).\n\n\nClaude Code
\n\n```bash\nclaude mcp add arc --scope user -- npx -y arc-control-mcp@latest\n```\n\nThe `--` is required. Without it, `claude mcp add` reads the `-y` as one of its\nown flags and registers the wrong command. Then check what was registered:\n\n```bash\nclaude mcp get arc\n```\n \n\n\nClaude Desktop
\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` and add\nthe `mcpServers` block above, merging it with any servers already listed. Quit\nand reopen Claude Desktop: the file is only read at launch.\n \n\n\nCursor
\n\nAdd the same `mcpServers` block to `~/.cursor/mcp.json` for every project, or to\n`.cursor/mcp.json` for one project.\n \n\n\nVS Code
\n\nVS Code uses `servers`, not `mcpServers`, in `.vscode/mcp.json` for a workspace\nor in the file opened by the **MCP: Open User Configuration** command:\n\n```json\n{\n \"servers\": {\n \"arc\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"arc-control-mcp@latest\"]\n }\n }\n}\n```\n\nOr from the command line:\n\n```bash\ncode --add-mcp '{\"name\":\"arc\",\"command\":\"npx\",\"args\":[\"-y\",\"arc-control-mcp@latest\"]}'\n```\n \n\n\nFrom a git checkout, for development
\n\n```bash\ngit clone https://github.com/DB-25/arc-control-mcp.git\ncd arc-control-mcp\nnpm install\nclaude mcp add arc-dev --scope user -- node \"$PWD/src/index.js\"\n```\n\nFor any other client, the same thing as JSON. The path has to be absolute: the\nclient's working directory is not yours.\n\n```json\n{\n \"mcpServers\": {\n \"arc-dev\": {\n \"command\": \"node\",\n \"args\": [\"/absolute/path/to/arc-control-mcp/src/index.js\"]\n }\n }\n}\n```\n\nRegister it under a different name than the published one, so you can tell which\ncopy answered. See [CONTRIBUTING.md](CONTRIBUTING.md).\n \n\nCheck the install without an MCP client. Neither call touches Arc, so both work\nbefore the permissions below are granted:\n\n```bash\nnpx -y arc-control-mcp@latest --version\nnpx -y arc-control-mcp@latest --help # tool count and environment variables\n```\n\n## The two macOS permissions\n\nBoth are asked for once, and both fail in a way that is confusing if you do not\nknow to look here.\n\n1. **Automation.** System Settings > Privacy & Security > Automation, enable\n **Arc** under the app that runs the server (Terminal, iTerm, Claude Code, your\n editor). Without it, *nothing* works: every tool fails on the first Apple\n Event.\n2. **Allow JavaScript from Apple Events.** Arc > Settings > Advanced. Without\n it, tab and window tools keep working (list, switch, close, open a URL) while\n everything that touches page content fails: no text, no HTML, no clicking, no\n scripts.\n\nBoth failures are mapped to an explanatory error rather than a raw AppleScript\ncode, so you will be told which one to fix.\n\n## Why not just reuse the Chrome server\n\nArc's scripting dictionary looks like Chrome's but differs in ways that break\nthe Chrome server outright:\n\n| | Chrome | Arc |\n|---|---|---|\n| Tab id | integer | UUID string |\n| Switch tab | `set active tab index of window` | `select` command on the tab |\n| Back / forward | works on window or tab | tab only |\n| New tab | `open location` | `make new tab` on a window or space |\n| Grouping | none | spaces, plus a pinned / unpinned / topApp location |\n\nThe Chrome server calls `parseInt(tab_id)` on every id, so against Arc every\ntool taking a tab id fails before reaching AppleScript. It also splits\nAppleScript's comma-joined output, which corrupts titles and URLs containing\ncommas.\n\n## Design\n\nNot restrictive by design. Anything the agent can reach, it can drive: any tab,\nany space, arbitrary JavaScript. The defaults are chosen so the user's browsing\nis not disturbed, but nothing is walled off.\n\n- **Implicit target**: a call with no `tab_id` uses a tab this agent opened. A\n read-only tool then falls back to whatever tab is active in Arc, because\n reading the page you already have open is useful and harmless. A tool that\n *changes* a tab does not fall back: with no tab of its own it is refused, so an\n agent cannot navigate or reload the tab you are working in just by leaving an\n argument out. Pass a `tab_id` to address any tab deliberately.\n- **Arguments are checked before anything runs**: every tool's schema is a Zod\n schema, the JSON Schema it advertises over MCP is generated from that, and the\n same schema validates the incoming call. A wrong type comes back as\n `Invalid arguments for click. selector: Invalid input: expected string,\n received number`, rather than as an obscure failure from inside the page.\n- **Ownership is information, not enforcement**: every tab is flagged `mine`, and\n `close_own_tabs` exists for cleanup. No tool refuses a tab you name with an\n explicit `tab_id`. The one refusal above is about an unnamed tab, not a named\n one.\n- **No focus stealing**: Arc auto-selects a newly created tab, so `open_url`\n puts the previous selection back, and only when Arc actually took it. If the\n user switched tabs while the page was opening, their choice stands. Pass\n `activate: true` to opt out.\n- **Background tabs are fully usable**: tabs in an unfocused space still load,\n render and script normally, so nothing needs to be brought to the front.\n\nScripts run through `osascript -l JavaScript` (JXA), so results come back as\nJSON rather than AppleScript's flat comma-joined lists. Tool arguments are\ninjected as a JSON literal bound to `P`, never concatenated into script source.\n\nEvery injected page script returns an explicit envelope, so a script that threw\nis reported as an error carrying the page's own message instead of arriving as\nan empty success. That distinction is the main thing 0.3.0 fixed.\n\nThe model never reads this README, so the handful of facts it needs before its\nfirst call are sent as MCP `instructions` at initialize: call `arc_status`\nfirst, prefer passing a `tab_id` over switching what the user is looking at,\n`text=` is substring matching, batch a known sequence, and page content is\nuntrusted data rather than instructions. A client that ignores `instructions`\nloses nothing but a few wasted calls.\n\n## Tools\n\n26 tools in six modules.\n\n### Tabs\n\n| Tool | Purpose |\n|---|---|\n| `list_tabs` | Every tab, or narrow with `scope: \"own\"`, `query`, `space`, `window_id`. Rows are flagged `mine` and `isActive`. |\n| `get_current_tab` | The tab a call with no `tab_id` would act on. |\n| `switch_to_tab` | Make a tab active in its window. `activate` also brings Arc to the front. |\n| `close_tab` | Close one tab. |\n| `close_own_tabs` | Close every tab this agent opened, leaving the user's alone. `include_stale` also closes tabs leaked by a dead previous run of the same label. |\n| `arc_status` | Owned tabs, whether the agent space exists, what a call with no `tab_id` resolves to (reported separately for read-only and for changing tools), and how many stale tabs a previous run left behind. |\n\n### Navigation\n\n| Tool | Purpose |\n|---|---|\n| `open_url` | Open a URL, launching Arc if needed. Options for `new_tab`, target `space`, `little_arc`, `activate`, `wait_until_loaded`. |\n| `go_back` / `go_forward` | Move a tab through its history, verified by checking the URL actually changed. |\n| `reload_tab` | Reload a tab. |\n| `wait_for_load` | Poll until the document is ready, optionally until the URL contains a substring. |\n\n### Content\n\n| Tool | Purpose |\n|---|---|\n| `get_page_content` | Visible text, whole page or every element matching a selector, joined. Always reports `matched`, so a partial answer is never silent, and flags truncation. |\n| `get_html` | Markup for the page or one element, outer or inner. Reports how many matched and takes `nth` to pick another. |\n| `query_elements` | Structured details per element: text, value, href, visibility, attributes. Reports `total` alongside `returned`. The main way to see what is on a page before acting. |\n| `get_links` | Links with text and resolved href, filterable by substring. |\n| `get_page_info` | Title, URL, ready state, meta description, a headings outline, and counts of links, forms, inputs, buttons and iframes. A cheap first look at an unfamiliar page. |\n\n### Interaction\n\n| Tool | Purpose |\n|---|---|\n| `click` | Scroll into view and dispatch a real pointer sequence, so framework handlers fire. `nth` picks among matches. |\n| `fill` | Set an input, textarea or contenteditable through the native setter, firing `input` and `change`. `submit: true` presses Enter afterwards. |\n| `select_option` | Choose an option by value or visible label. |\n| `press_key` | Dispatch a key press to an element or the focused element. |\n| `scroll` | Scroll the page by direction and amount, or scroll one element into view. |\n| `wait_for_selector` | Poll until an element is `present`, `visible` or `absent`. |\n\n### Spaces\n\n| Tool | Purpose |\n|---|---|\n| `list_spaces` | Spaces in the front window with tab counts, which is active, and `topAppCount` for the sidebar favourites that belong to no space. |\n| `focus_space` | Switch the front window to a space. Rarely needed: unfocused tabs are fully scriptable. |\n\n### Scripting\n\n| Tool | Purpose |\n|---|---|\n| `execute_javascript` | Run JavaScript in a tab and return the result. Takes a bare expression or a statement body, validated before injection. |\n| `batch` | Run several tools in order in one call. `continue_on_error` keeps going past a failure. |\n\nEvery tool states its full set of MCP annotations rather than leaving any to a\nclient's inference, because the spec's defaults are counterintuitive:\n`destructiveHint` and `openWorldHint` both default to true. Read tools are\nannotated read-only. Four tools are annotated destructive: `close_tab` and\n`close_own_tabs`, plus `execute_javascript` and `batch`, which can do anything a\npage can do. `openWorldHint` is true for everything that touches page content,\nand false only for the tools that read or move Arc's own tab and space\nbookkeeping.\n\n### Selectors\n\nEvery selector argument accepts either:\n\n- a **CSS selector**, passed straight to `querySelectorAll`, or\n- **`text=Some label`**, which matches on visible text. This is **substring**\n matching, and it is case-insensitive. Exact matches are ranked first, so\n `text=Save` prefers a button labelled exactly \"Save\" over one labelled \"Save\n and close\". Innermost matches win over their ancestors. Tools that act on a\n single element report how many matched, so a vague label is visible rather\n than silent; pass `exact: true` to require the whole text, or `nth` to pick a\n different match.\n\n`execute_javascript` takes either a bare expression (`document.title`) or a\nstatement body (`const rows = [...]; return rows.length`). Which one it used is\nreported as `form`, either `\"expression\"` or `\"statement\"`. A statement body\nyields a value only through `return`: `let n = 2; n * 3` comes back as `null`\nwith a note telling you to add one, because producing `6` there would require\n`eval` inside the page and that breaks on any site with a strict\nContent-Security-Policy. Broken syntax is rejected in Node with the real parser\nmessage, before Arc is contacted at all.\n\nThe `form` field matters because it is what makes a legitimate `null`\ndistinguishable from a script that failed, which used to be impossible. If a value\nhas no useful JSON representation, for example a DOM node or `window`, the\nresponse carries a `note` explaining that rather than a bare `{}`.\n\n### The page helper library\n\n`execute_javascript` runs with the same helper library the built-in tools use,\nbound to `A`: `A.all`, `A.one`, `A.click`, `A.setValue`, `A.describe`,\n`A.visible`, `A.key`. So `A.all('text=Sign in').length` works, and anything you\ncan do in the console you can do here.\n\n### `batch`\n\nEach `osascript` spawn costs a few hundred milliseconds, so batching matters\nmore here than it would over CDP:\n\n```json\n{\"steps\": [\n {\"tool\": \"fill\", \"args\": {\"selector\": \"#user\", \"value\": \"db\"}},\n {\"tool\": \"fill\", \"args\": {\"selector\": \"#pass\", \"value\": \"...\"}},\n {\"tool\": \"click\", \"args\": {\"selector\": \"text=Sign in\"}},\n {\"tool\": \"wait_for_selector\", \"args\": {\"selector\": \".dashboard\"}}\n]}\n```\n\nThe tab is reported once for the batch rather than repeated per step, and\nrepeated only when it actually changes mid-batch.\n\nTab ids are UUID strings and are not stable across a close and reopen, so call\n`list_tabs` rather than reusing an old one.\n\n## Environment variables\n\n| Variable | Default | Effect |\n|---|---|---|\n| `ARC_MCP_LABEL` | `default` | Names this agent's tab ownership. Two agents with different labels never see each other's owned tabs. |\n| `ARC_MCP_SPACE` | `Agent` | The Arc space new tabs open into, when a space with that name exists. |\n| `ARC_MCP_STATE_DIR` | `~/Library/Application Support/arc-control-mcp` | Where tab ownership is recorded, so a restarted agent can clean up the tabs its previous run left behind. |\n\n## Isolation, and why not a separate window\n\nAn Arc window is not an isolation boundary. Every window showing a space shares\nthat space's whole tab list, so a second window displays the same tabs.\nVerified: a scripted new window listed the same 27 tabs as the original.\n\nThe only real boundary is a **space**. Create one named `Agent` (or set\n`ARC_MCP_SPACE`) and every tab this server opens goes there, out of the sidebar\nyou are working in. Without it, tabs open in the main window alongside yours;\neverything still works, they are just visible. `arc_status` reports which mode\nis active.\n\nAgents are separated from each other as well: each runs its own copy of the\nserver, ownership is tracked per session, and `ARC_MCP_LABEL` names it. One\nagent's `list_tabs scope=own` and `close_own_tabs` never see another's tabs,\neven when both use the same label. Tabs left behind by a dead earlier run are\nreported by `arc_status` as stale and only closed if you ask, with\n`close_own_tabs include_stale=true`, so a restart can never sweep away a live\nsibling's tabs. Agents do still share the one `Agent` space in the sidebar,\nsince Arc will not let a script create a space.\n\n## Known Arc limitations\n\nVerified in August 2026; worth retesting after an Arc update. These are Arc's\nbehaviour, not decisions made here.\n\n- Setting a tab's `location` (topApp / pinned / unpinned) is marked writable but\n always fails with `-10000`, so there is no pin/unpin tool.\n- Closing a window does nothing, so the server never creates windows.\n- Creating a space silently no-ops, which is why the space is made by hand.\n- `mode: \"incognito\"` is ignored when creating a window.\n- Little Arc tabs never appear in `Arc.windows`, so they cannot be read or\n closed after creation.\n- Closed windows linger in `Arc.windows` as invisible phantoms whose `activeTab`\n throws, so lookups filter on `visible()`.\n- `space.tabs` excludes topApp favourites, so those report `space: null`.\n `list_spaces` reports `topAppCount` so its numbers reconcile with `list_tabs`.\n- A bulk `window.tabs()` fetch raises `-1700`, but bulk property reads\n (`window.tabs.id()`) work and are ~10x fewer Apple Events.\n- `Arc.execute` returns the JSON *encoding* of the page value, so strings arrive\n quoted and are unwrapped before being returned.\n- `Arc.goBack` does nothing on a background tab, so `go_back` and `go_forward`\n go through the page's own history API instead and verify the URL changed.\n\n### Limitations of synthetic events\n\nEverything this server does in a page is a synthetic event, dispatched from\ninjected JavaScript. Widgets gated on trusted events (`event.isTrusted`) cannot\nbe driven that way, and there is no workaround inside this design: Arc's\n`execute javascript` gives no CDP access, so there is no way to inject a real\ninput event.\n\nVerified against Wikipedia's search box. `fill` sets the value correctly, but\nthe suggestion dropdown never opens. Hand-dispatching per-character\n`keydown`/`input`/`keyup` does not help either.\n\nThe workaround does work, and is usually what you wanted anyway:\n\n- `fill` with `submit: true`, which presses Enter and navigates, or\n- navigate straight to the search URL with `open_url`.\n\nIf a widget only reacts to a suggestion list, a hover preview, or a drag, expect\nit not to react here.\n\n## Troubleshooting\n\nThe server rewrites Arc's raw AppleScript codes into messages that name the\nremedy. If you see:\n\n| Message | What to do |\n|---|---|\n| `Permission denied: controlling Arc needs automation access.` | Grant Automation in System Settings, then **restart the calling app**. The permission is only re-read at launch. |\n| `Arc is blocking JavaScript from Apple Events.` | Turn on \"Allow JavaScript from Apple Events\" in Arc > Settings > Advanced. |\n| `Arc is not running. Launch Arc, or use open_url, which starts it.` | Launch Arc, or just call `open_url`. |\n| `Arc is running but has no open windows.` | Arc keeps running with every window closed. Press Cmd-N. |\n| `No open Arc tab has id X. Run list_tabs to get current tab ids` | The tab was closed, or the id is stale. Ids change across a close and reopen. |\n| `No Arc space matches \"X\".` | Run `list_spaces`. Space titles are case-sensitive, and a space must be created by hand. |\n| `No element on the page matches the selector \"X\".` | Check the page with `query_elements` first. With `text=`, remember it is substring matching on visible text only. |\n| `The page script failed: SyntaxError: ...` | Your selector or code is invalid. The message is the page's own, so it says which. |\n| `The page script returned nothing recognisable.` | Usually the JavaScript-from-Apple-Events permission, sometimes a tab that navigated mid-call. Retry once, then check the permission. |\n| `Arc did not respond within 30s.` | Arc is showing a modal dialog (a permission prompt, a save sheet) or is stuck loading. Look at the window. |\n| `Not a valid URL: X. Include a scheme, for example https://` | Prefix the URL with `https://`. |\n| `(This is an internal arc-control error, not an Arc or page problem.)` | A bug here. Please [open an issue](https://github.com/DB-25/arc-control-mcp/issues) with the tool, arguments and full error. |\n\nIf a tool reports `ok: false` with `timedOut`, that is not an error: it is\n`wait_for_load` or `wait_for_selector` telling you the condition never became\ntrue, with `waitedMs` and what it did see.\n\n## Layout\n\n```\nsrc/\n index.js MCP wiring, --version and --help\n registry.js composes tool modules, validates tool/handler parity at load\n jxa.js osascript runner, Arc preamble, error mapping\n state.js per-session tab ownership\n page-lib.js helper library injected into the page as `A`\n tools/\n shared.js common schemas and run helpers\n tabs.js list, switch, close, status\n navigation.js open, back, forward, reload, wait for load\n content.js text, html, structured queries, links, page info\n interact.js click, fill, select, keys, scroll, wait for selector\n spaces.js Arc spaces\n scripting.js raw JavaScript and batch\n```\n\nAdding a module means creating `tools/.js` exporting `tools` and\n`handlers`, then listing it in `registry.js`. The registry throws at startup on\na duplicate name, a tool with no handler, or a handler with no tool. See\n[CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Project docs\n\n- [CHANGELOG.md](CHANGELOG.md), including what 0.3.0 fixed\n- [CONTRIBUTING.md](CONTRIBUTING.md)\n- [SECURITY.md](SECURITY.md), including the threat model: this server runs\n arbitrary JavaScript in your real logged-in browser by design\n- [docs/agent-review-2026-08-31.md](docs/agent-review-2026-08-31.md), the review\n that scoped 0.3.0\n- [LICENSE](LICENSE), MIT\n",
"bytes": 22529,
"sha": "a26b66505fcb72dca2fae0acd7ae1e3d33b7c51b1ca4f80c328b0f6b0864bcd1",
"repo_slug": "db-25/arc-control-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_db_25_arc_control_mcp_54f0c308/readme"
}