Hunch MCP server

Read from the package source without running it. The installed server may list more.

• act
• app_capabilities
• app_recover
• app_target
• applescriptwrite action

  Run AppleScript to control scriptable native apps FOCUS-FREE via Apple Events — the app's own command layer, not its UI/keyboard/focus. Unlocks Mail, Messages, Notes, Reminders, Calendar, Music, Finder, Safari, Keynote, etc. (e.g. 'tell application "Music" to play', or 'tell application "Safari" to get URL of current tab of front window'). Returns the script's output or the error.

• clipboard_get

  Read the clipboard's text — focus-free (no ⌘C needed).

• clipboard_setwrite action

  Put text on the clipboard — focus-free (move data around without ⌘C/⌘V keystrokes).

• file_op

  Focus-free filesystem operations by path: op='move' or 'copy' (src -> dst; dst may be a folder or a new path), or op='mkdir' (create a folder at src). For MULTIPLE operations pass batch=[{"op","src","dst"},...] and they all run in ONE call — sorting a folder is one call, not one per file. To delete, use `trash`.

• find

  Search an app's WHOLE accessibility tree for matching elements — the cheap way to locate one control in a huge window without reading a full snapshot. Filters: `role` (e.g. "button", "AXTextField", "row" — case-insensitive, "AX" prefix optional) and/or `name_contains` (case-insensitive substring of the element's title/description/value). Returns one line per match: an ancestor breadcrumb, then the

• focus_app

  Bring an app to the front (reliable OS call), and target it for snapshots. ALWAYS pass `reason` — one short sentence for WHY you're switching the user's view (shown to them in the focus warning).

• launch_app

  Launch or focus an app, then target it (reliable OS call — use instead of clicking Dock icons). In simultaneous mode it launches in the BACKGROUND so it doesn't steal your view. Set force_accessibility=True for an Electron/Chromium app (Spotify, Discord, Slack, Notion, VS Code) whose tree reads empty — it relaunches the app so its accessibility tree becomes visible to snapshot. Pass `reason` — one

• list_apps

  List the running GUI apps you can target with snapshot(app=...).

• list_credentials

  List the service NAMES the user has saved credentials for (e.g. "google", "openai"). Returns names + kind ONLY — never any values. Two kinds: username+password logins (use web_fill_login) and single protected values like API keys (use web_fill_secret).

• notify_user

  Alert the user when Hunch needs them SHORTLY — to finish a login, approve a 2FA / verification prompt, solve a captcha, or make a decision. Brings the Hunch window back up (or fires a desktop notification when running outside the app and the user enabled `notifications.user_attention`). Call this the moment you hit a step only the human can do, so they don't have to watch the screen.

• open_file

  Open a file/folder/URL with its default app (or a named app) — focus-free launch. Also opens web URLs and app deep-links (e.g. 'spotify:track:...', 'mailto:...').

• quit_app

  Quit an app via the OS — reliable regardless of focus (use instead of ⌘Q, which is unreliable on background apps).

• request_focus

  Ask the user's permission BEFORE a focus-stealing step you'll do via OTHER tools (e.g. focus_app / launch_app bringing an app to the front). Pops a one-click 'Go ahead / Cancel' dialog and returns their choice. You do NOT need this for `act`'s key / click_xy / ref-less type — act pops the same dialog automatically. If approved, do the action, then return focus to the user's previous app when done.

• reveal_in_finder

  Reveal/select item(s) in a Finder window by path. (This one does bring Finder forward — it's an explicit 'show me these files' action.)

• screenshot

  See the screen as a PNG image — for surfaces the tree genuinely can't show (canvas apps, an image, a photo/file-preview thumbnail). NOT for reading UI you could get from `snapshot`: if the tree looked thin, `click` into the pane and re-`snapshot` instead. A screenshot only shows the FRONTMOST app, so in the background it usually shows the user's OTHER app, not your target — and it can't be acted o

• simultaneous_mode

  Turn simultaneous mode on/off. When ON, Hunch never steals your cursor/keyboard or switches your view: it reads apps WITHOUT bringing them forward, launches apps in the background, runs only the focus-free actions (click/select/set-a-field by ref), and REFUSES shared-input actions (typed keystrokes, key combos, pixel clicks) that would disrupt you. Background AX coverage is operation- and state-de

• snapshot

  See the screen as an accessibility tree. Each element is one line tagged with a [ref] like [e12]; you act on elements by ref. Pass an app name to target that app's focused window, or leave blank for the frontmost app.

• trash

  Move file(s)/folder(s) to the Trash BY PATH — FOCUS-FREE and reversible. Use this to delete files instead of driving Finder + ⌘⌫ (which steals focus and is fragile). Accepts absolute or ~ paths. Files go to the Trash, so it's recoverable.

• web_actwrite action

  Execute focus-free page actions on the bound Safari or CDP app, then return the updated tree. Each: {"action":"click","ref":"e12"} | {"action":"type","ref":"e12","text":"hi"} | {"action":"click_xy","x":500,"y":250} | {"action":"drag","from_x":10,"from_y":20, "to_x":200,"to_y":220} | {"action":"key","key":"return"} | {"action":"navigate","url":"https://..."}. `type` REPLACES a field's content (no m

• web_fill_login

  Fill the CURRENT CDP page's login form (username + password) using the user's SAVED credential for `service`, WITHOUT the values ever entering your context. You pass ONLY the service name; Hunch reads the secret from the macOS Keychain and types it straight into the page, returning only which fields were filled. Call web_open first and make sure the login form is visible. For two-step logins (e.g.

• web_fill_secret

  Type the user's SAVED protected value (API key / token) for `service` into a field on the CURRENT CDP page, WITHOUT the value ever entering your context. web_snapshot first and pass the target field's `ref`; Hunch reads the secret from the macOS Keychain and types it straight into that field, replacing its content — you only learn that it was filled. Omit `ref` to type at the currently-focused ele

• web_login

  Sign into the persistent Hunch CDP profile ONCE (there is no way to reuse the user's existing browser login over CDP — modern Chrome + site device-bound cookies prevent it). `app` is the BROWSER name (default "Google Chrome"); `url` is the site's login/home page (e.g. "https://mail.google.com/") — do not pass a website as `app`. Opens the browser in the BACKGROUND at that URL (it does NOT steal fo

• web_open

  Open Safari through the Hunch extension, or Chromium/Electron through CDP, for FOCUS-FREE background control — read, click, and type in the BACKGROUND without stealing your cursor/keyboard or switching your view. This is the way to drive these apps simultaneously with the user (AX can't). Then use web_snapshot / web_act.

• web_restart

  Recover a BROKEN CDP browser by quitting and reopening it fresh. Kills only the Hunch CDP instance (never the user's normal browser), relaunches on the SAME persistent profile (login kept), reloads `url` if given, and returns the fresh tree.

• web_screenshot

  PNG of the CDP-controlled page ITSELF (focus-free, via CDP) — for genuinely visual web content the tree can't convey (a chart, canvas, image, rendered PDF). Use THIS, never the OS `screenshot` tool, for anything in the background browser: the OS one grabs the physical screen and would capture the user's own foreground window instead of this page. Call web_open first.

• web_snapshot

  Look at the bound Safari or CDP browser/Electron page as an accessibility tree ([ref] per element). Call web_open first.

• web_switch_tab

  Switch the CDP session to a specific browser tab by index (see web_tabs), then web_snapshot to read it. Use when auto-follow landed on the wrong tab, or to return to an earlier one.

• web_tabs

  List the open browser tabs/windows in the bound Safari or CDP session — index, title, URL, and which is current (*). New tabs opened by a click or form are AUTO-FOLLOWED on the next web_snapshot; use web_switch_tab only to override that (go back to a prior tab, or pick a different one).

• Code scan32 source files scanned25/25
• –Live reliabilityno gateway calls yet and no remote to proben/a
• –Tool poisoningtools not inspected (local package is not executed); not countedn/a
• Auth qualitylocal package, no credentials required12/15
• Maintenancelast push 6 days ago15/15
• Maintainer identityregistry namespace matches repository owner; GitHub account older than a year8/10

Hunch: common questions

Is Hunch MCP server safe?

Yes, by our scan: it is graded A (92/100). Read the Hunch safety report

How do I install Hunch?

It runs on your machine. Copy the Claude Code, Claude Desktop or Cursor config from the install section.

Does Hunch need an API key?

Not as far as the registry entry and our scan can tell: no credentials are declared or required.

Is Hunch maintained?

The last commit was 6 days ago (2026-09-13). The latest release is v0.6.6.

What can I use instead of Hunch?

Servers from other publishers that do the same job: Mac Control MCP server, FlutterSDK Dusk MCP server and Swing MCP server. Compare all Hunch alternatives.