hunch — Claude Code MCP server: what it does, how to install
Controls macOS desktop and native applications in the background without stealing window focus. Helpful when an agent needs to handle Mac tasks while you keep typing.
claude mcp add hunch -- uvx hunch-sdkWhat hunch does
Hunch operates entirely as a local child process via stdio JSON-RPC. It does not open network ports. No background daemons or external cloud services exist here. For desktop control, the server relies on four distinct layers: direct OS-API calls for files, osascript for scriptable tools like Mail, browser bridges via CDP, and Accessibility tree inspections for UI elements.
The tool requires macOS 13 or newer. Accessibility permissions must be granted to the parent application running the server, such as your terminal or code editor. Screen Recording access is strictly optional, reserved as a fallback for software with empty accessibility trees.
What it helps with
- interact with native desktop interfaces without moving the mouse pointer
- script apps like Mail and Notes via AppleScript calls
- inspect background web pages in Chromium or Safari sessions
- manipulate local files and trash items using native system endpoints
Example prompts for the agent
- Check
Mailfor unread items and summarize the latest message - Open a background Safari session to check the deployment dashboard
- Inspect the Notes window and read the contents of the top note
How to install hunch
Platform CLI
claude mcp add hunch -- uvx hunch-sdkuvx runs the command named after the package; if the README names another one, use uvx --from hunch-sdk <command>
Platform CLI
codex mcp add hunch -- uvx hunch-sdkuvx runs the command named after the package; if the README names another one, use uvx --from hunch-sdk <command>
Config file
{
"mcpServers": {
"hunch": {
"command": "uvx",
"args": [
"hunch-sdk"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from hunch-sdk <command>
Config file
{
"servers": {
"hunch": {
"type": "stdio",
"command": "uvx",
"args": [
"hunch-sdk"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from hunch-sdk <command>
Platform CLI
gemini mcp add hunch uvx hunch-sdkuvx runs the command named after the package; if the README names another one, use uvx --from hunch-sdk <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about hunch
How to install hunch in Claude Code?
Run claude mcp add hunch -- uvx hunch-sdk. Restart your agent session afterward to load the tools.
What makes hunch focus-free?
It inspects accessibility trees and targets specific element references directly instead of relying on active screen coordinate clicks. Your foreground windows and active cursor remain untouched during execution.
What macOS permissions does hunch require?
You need macOS 13 or later. You must grant Accessibility access to your parent MCP host inside Privacy & Security settings, while Automation prompts appear once per targeted application.
