mac-use

A macOS 14+ MCP server for controlling native macOS windows through Accessibility. An optional Chrome extension lets it work in new background tabs in your current Chrome profile.

English | Español | Português (Brasil)

---

English

Why use mac-use?

mac-use is designed to work alongside your normal Mac use and compatible computer-use tools. For native windows, it acts through Accessibility on the exact window you choose, without activating that window or moving your physical pointer. It waits for recent keyboard or mouse activity to settle and stops if you take over. Its shared lock serializes actions with other computer-use tools that honor the same lock, including RemoteCode. Tools that do not use that lock cannot be guaranteed conflict-free. In Chrome, mac-use opens background tabs and stops controlling a tab as soon as you select it.

What you need

• macOS 14 or newer
• Xcode Command Line Tools (xcode-select --install)
• An MCP client: Distill, Codex, Claude Code, or Grok Build
• Google Chrome only if you want the browser tools

1. Build the MCP server

Open Terminal and run:

git clone git@github.com:samuelfaj/mac-use.git
cd mac-use
swift build -c release

If you do not use GitHub SSH, replace the first command with the clone URL you normally use. Keep this folder in place after setup. The MCP clients below all start the same executable from this folder.

2. Connect it to your MCP client

Run one command for the client you use, from inside the mac-use folder:

• Distill:

  distill mcp add mac-use -- "$(pwd)/.build/release/mac-use-mcp"
  distill mcp doctor mac-use

• Codex:

  codex mcp add mac-use -- "$(pwd)/.build/release/mac-use-mcp"

• Claude Code:

  claude mcp add --scope user mac-use -- "$(pwd)/.build/release/mac-use-mcp"

• Grok Build:

  grok mcp add --scope user mac-use -- "$(pwd)/.build/release/mac-use-mcp"

If the client was already open, restart it after adding the server. In Claude Code, approve the server if prompted. Keep the repository at the same path; each client starts the executable from there.

Install the agent skill globally

Install the bundled mac-use skill from this repository for Codex, Claude Code, and Distill/Grok Build (which share ~/.grok/skills):

for root in "$HOME/.codex/skills" "$HOME/.claude/skills" "$HOME/.grok/skills"; do
  mkdir -p "$root/mac-use"
  cp "skills/mac-use/SKILL.md" "$root/mac-use/SKILL.md"
done

Start a new client session after installation. The skill requires agents to close resources they create, including after failures, preserve user-owned resources, and verify cleanup. The MCP also advertises a cleanup reminder. This is agent guidance, not an automatic sandbox; the shared Chrome profile retains normal history and site state.

3. Allow macOS access for native windows

When macOS asks, allow Accessibility and Screen Recording for the app that runs your MCP client. These permissions are needed only for native macOS windows. You can use the MCP doctor tool on a window to check permissions.

4. Optional: set up Chrome

The Chrome extension is included in this repository. Load it into the same Chrome profile you plan to use with mac-use:

1. Open chrome://extensions.

2. Turn on Developer mode.

3. Click Load unpacked and select the chrome-extension folder inside the cloned mac-use folder.

4. Open the extension's details page and copy its 32-letter ID. The screenshot shows where to find it.

   

5. In Terminal, from the mac-use folder, register the extension with the native host. Replace the example ID with the one from your Chrome page:

   .build/release/mac-use-mcp install-chrome-host YOUR_32_LETTER_EXTENSION_ID

6. Click the mac-use extension icon in Chrome. Its badge should say ON. In your MCP client, call browser_status; it should report connected: true.

The extension uses Chrome's native messaging to connect to the MCP server. If you move the repository or reload the extension and its ID changes, run the registration command again with the new path or ID. Use a regular Chrome window, not Incognito.

Try it

• For a native window, call list_windows, then use the returned exact window details with the relevant mac-use tools.
• For Chrome, call browser_status, then browser_open with an http:// or https:// address. It opens a new background tab. Use browser_snapshot to inspect it and browser_act for supported page actions.

distill mcp doctor checks that the MCP server starts and exposes its tools. It does not confirm macOS permissions or a Chrome connection.

If Chrome says "Specified native messaging host not found"

The extension's native host registration is missing or does not match the extension ID. From the mac-use folder, run the registration command again with the current ID from chrome://extensions. Then click the extension icon to reconnect. Check that .build/release/mac-use-mcp is still at the same path and that the extension is loaded in the Chrome profile you are using.

Privacy and control

The Chrome extension can read page text and form values, except password values. It can click, fill, type, and scroll in tabs that it opened. It does not automate your selected tab; selecting an automated tab gives control back to you. When browser_close runs or the extension disconnects, it best-effort closes only tabs it created that still appear inactive and were not selected by the user. Chrome cannot make the activity check and tab removal atomic, so a selection racing with removal may still be closed. Page content and snapshots are visible to your Distill session, so do not use the browser tools on pages containing information you do not want to share with that session. The extension requests access to HTTP and HTTPS sites because it needs to operate on pages you ask it to open.

---

Español

¿Por qué usar mac-use?

mac-use está diseñado para funcionar junto con tu uso normal del Mac y con otras herramientas de control del ordenador compatibles. En ventanas nativas, actúa mediante Accesibilidad sobre la ventana exacta que eliges, sin activarla ni mover el puntero físico. Espera a que termine la actividad reciente del teclado o del ratón y se detiene si tomas el control. Su bloqueo compartido ordena las acciones junto con otras herramientas que respetan el mismo bloqueo, incluido RemoteCode. No se puede garantizar que no haya conflictos con herramientas que no lo utilizan. En Chrome, mac-use abre pestañas en segundo plano y deja de controlarlas cuando seleccionas una.

Requisitos

• macOS 14 o posterior
• Xcode Command Line Tools (xcode-select --install)
• Un cliente MCP: Distill, Codex, Claude Code o Grok Build
• Google Chrome solo si quieres usar las herramientas del navegador

1. Compilar el servidor MCP

Abre Terminal y ejecuta:

git clone git@github.com:samuelfaj/mac-use.git
cd mac-use
swift build -c release

Si no usas SSH de GitHub, cambia el primer comando por la URL que utilizas normalmente. Conserva esta carpeta después de la instalación. Los clientes MCP de abajo inician el mismo ejecutable desde esta carpeta.

2. Conectarlo a tu cliente MCP

Ejecuta un solo comando, según el cliente que uses, desde la carpeta mac-use:

• Distill:

  distill mcp add mac-use -- "$(pwd)/.build/release/mac-use-mcp"
  distill mcp doctor mac-use

• Codex:

  codex mcp add mac-use -- "$(pwd)/.build/release/mac-use-mcp"

• Claude Code:

  claude mcp add --scope user mac-use -- "$(pwd)/.build/release/mac-use-mcp"

• Grok Build:

  grok mcp add --scope user mac-use -- "$(pwd)/.build/release/mac-use-mcp"

Si el cliente ya estaba abierto, reinícialo después de añadir el servidor. En Claude Code, acepta el servidor si aparece una solicitud. Conserva el repositorio en la misma ruta; cada cliente inicia el ejecutable desde allí.

Instalar la skill del agente globalmente

Instala la skill mac-use incluida en este repositorio para Codex, Claude Code y Distill/Grok Build (que comparten ~/.grok/skills):

for root in "$HOME/.codex/skills" "$HOME/.claude/skills" "$HOME/.grok/skills"; do
  mkdir -p "$root/mac-use"
  cp "skills/mac-use/SKILL.md" "$root/mac-use/SKILL.md"
done

Inicia una sesión nueva del cliente después de instalarla. La skill exige cerrar los recursos creados por el agente incluso ante errores, preservar los recursos del usuario y verificar la limpieza. El MCP también comunica un recordatorio. Son instrucciones para el agente, no un entorno aislado automático; el perfil compartido de Chrome conserva su historial y los datos de los sitios.

3. Permitir el acceso de macOS a las ventanas nativas

Cuando macOS lo solicite, permite Accesibilidad y Grabación de pantalla para la aplicación que ejecuta tu cliente MCP. Estos permisos solo hacen falta para controlar ventanas nativas de macOS. Puedes usar la herramienta MCP doctor sobre una ventana para comprobar los permisos.

4. Opcional: configurar Chrome

La extensión de Chrome está incluida en este repositorio. Cárgala en el mismo perfil de Chrome que quieras usar con mac-use:

1. Abre chrome://extensions.

2. Activa el Modo de desarrollador.

3. Haz clic en Cargar descomprimida y selecciona la carpeta chrome-extension dentro de la carpeta clonada mac-use.

4. Abre los detalles de la extensión y copia su ID de 32 letras. La imagen indica dónde encontrarlo.

   

5. En Terminal, desde la carpeta mac-use, registra la extensión con el host nativo. Sustituye el ID de ejemplo por el que aparece en Chrome:

   .build/release/mac-use-mcp install-chrome-host ID_DE_32_LETRAS

6. Haz clic en el icono de mac-use en Chrome. El indicador debe mostrar ON. En tu cliente MCP, llama a browser_status; la respuesta debe incluir connected: true.

La extensión usa la mensajería nativa de Chrome para conectarse al servidor MCP. Si mueves el repositorio o vuelves a cargar la extensión y cambia su ID, ejecuta otra vez el comando de registro con la ruta o el ID nuevos. Usa una ventana normal de Chrome, no el modo incógnito.

Pruébalo

• Para una ventana nativa, llama a list_windows y usa los datos exactos de la ventana con las herramientas correspondientes de mac-use.
• Para Chrome, llama a browser_status y después a browser_open con una dirección http:// o https://. Se abrirá una pestaña nueva en segundo plano. Usa browser_snapshot para verla y browser_act para realizar las acciones disponibles.

distill mcp doctor comprueba que el servidor MCP se inicia y ofrece sus herramientas. No comprueba los permisos de macOS ni la conexión con Chrome.

Si Chrome muestra "Specified native messaging host not found"

Falta el registro del host nativo o el ID registrado no coincide con el de la extensión. Desde la carpeta mac-use, ejecuta de nuevo el comando de registro con el ID actual de chrome://extensions. Después, haz clic en el icono de la extensión para conectarla. Comprueba que .build/release/mac-use-mcp siga en la misma ruta y que la extensión esté cargada en el perfil de Chrome que estás usando.

Privacidad y control

La extensión de Chrome puede leer el texto de las páginas y los valores de los formularios, excepto las contraseñas. Puede hacer clic, rellenar campos, escribir y desplazarse en las pestañas que abrió. No controla la pestaña seleccionada; si seleccionas una pestaña automatizada, recuperas el control. Al ejecutar browser_close o desconectarse la extensión, intenta cerrar únicamente las pestañas que creó y que siguen inactivas y no fueron seleccionadas por el usuario. Chrome no puede hacer atómicas la comprobación de actividad y la eliminación de la pestaña; por eso, una selección que coincida con la eliminación todavía podría cerrarse. El contenido y las capturas de las páginas quedan visibles para tu sesión de Distill. No uses estas herramientas en páginas con información que no quieras compartir con esa sesión. La extensión solicita acceso a sitios HTTP y HTTPS para poder trabajar en las páginas que le pidas abrir.

---

Português (Brasil)

Por que usar o mac-use?

O mac-use foi feito para conviver com o uso normal do Mac e com outras ferramentas de controle do computador que sejam compatíveis. Em janelas nativas, ele atua pela Acessibilidade na janela exata que você escolheu, sem ativá-la nem mover o cursor físico. Ele espera a atividade recente do teclado ou do mouse terminar e para quando você assume o controle. O bloqueio compartilhado coordena as ações com outras ferramentas que respeitam o mesmo bloqueio, incluindo o RemoteCode. Não é possível garantir que ferramentas que ignoram esse bloqueio não entrem em conflito. No Chrome, o mac-use abre abas em segundo plano e deixa de controlá-las assim que você as seleciona.

O que você precisa

• macOS 14 ou mais recente
• Xcode Command Line Tools (xcode-select --install)
• Um cliente MCP: Distill, Codex, Claude Code ou Grok Build
• Google Chrome somente se você quiser usar as ferramentas do navegador

1. Compile o servidor MCP

Abra o Terminal e execute:

git clone git@github.com:samuelfaj/mac-use.git
cd mac-use
swift build -c release

Se você não usa SSH do GitHub, substitua o primeiro comando pela URL que costuma usar. Mantenha essa pasta no mesmo lugar depois da instalação. Os clientes MCP abaixo iniciam o mesmo executável dentro dessa pasta.

2. Conecte ao seu cliente MCP

Execute apenas um comando, de acordo com o cliente que você usa, dentro da pasta mac-use:

• Distill:

  distill mcp add mac-use -- "$(pwd)/.build/release/mac-use-mcp"
  distill mcp doctor mac-use

• Codex:

  codex mcp add mac-use -- "$(pwd)/.build/release/mac-use-mcp"

• Claude Code:

  claude mcp add --scope user mac-use -- "$(pwd)/.build/release/mac-use-mcp"

• Grok Build:

  grok mcp add --scope user mac-use -- "$(pwd)/.build/release/mac-use-mcp"

Se o cliente já estiver aberto, reinicie-o depois de adicionar o servidor. No Claude Code, aprove o servidor se aparecer uma solicitação. Mantenha o repositório no mesmo caminho; cada cliente inicia o executável a partir dele.

Instale a skill do agente globalmente

Instale a skill mac-use incluída neste repositório para Codex, Claude Code e Distill/Grok Build (que compartilham ~/.grok/skills):

for root in "$HOME/.codex/skills" "$HOME/.claude/skills" "$HOME/.grok/skills"; do
  mkdir -p "$root/mac-use"
  cp "skills/mac-use/SKILL.md" "$root/mac-use/SKILL.md"
done

Inicie uma nova sessão do cliente após instalar. A skill exige fechar os recursos criados pelo agente inclusive em caso de erro, preservar os recursos do usuário e verificar a limpeza. O MCP também fornece um lembrete. São instruções para o agente, não um isolamento automático; o perfil compartilhado do Chrome mantém histórico e dados dos sites.

3. Permita o acesso do macOS às janelas nativas

Quando o macOS solicitar, permita Acessibilidade e Gravação de Tela para o aplicativo que inicia seu cliente MCP. Essas permissões são necessárias apenas para controlar janelas nativas do macOS. Você pode usar a ferramenta MCP doctor em uma janela para verificar as permissões.

4. Opcional: configure o Chrome

A extensão do Chrome está incluída neste repositório. Carregue-a no mesmo perfil do Chrome que pretende usar com o mac-use:

1. Abra chrome://extensions.

2. Ative o Modo do desenvolvedor.

3. Clique em Carregar sem compactação e selecione a pasta chrome-extension dentro da pasta clonada mac-use.

4. Abra os detalhes da extensão e copie o ID de 32 letras. A imagem mostra onde encontrá-lo.

   

5. No Terminal, dentro da pasta mac-use, registre a extensão com o host nativo. Troque o ID de exemplo pelo ID exibido no Chrome:

   .build/release/mac-use-mcp install-chrome-host SEU_ID_DE_32_LETRAS

6. Clique no ícone da extensão mac-use no Chrome. O indicador deve mostrar ON. No seu cliente MCP, chame browser_status; a resposta deve incluir connected: true.

A extensão usa o sistema de mensagens nativas do Chrome para se conectar ao servidor MCP. Se você mover o repositório ou recarregar a extensão e o ID mudar, execute novamente o comando de registro com o caminho ou ID atualizado. Use uma janela normal do Chrome, não o modo anônimo.

Teste

• Para uma janela nativa, chame list_windows e use os dados exatos da janela com as ferramentas correspondentes do mac-use.
• Para o Chrome, chame browser_status e depois browser_open com um endereço http:// ou https://. Uma nova aba será aberta em segundo plano. Use browser_snapshot para conferir a página e browser_act para executar as ações disponíveis.

distill mcp doctor verifica se o servidor MCP inicia e disponibiliza as ferramentas. Ele não verifica as permissões do macOS nem a conexão com o Chrome.

Se o Chrome mostrar "Specified native messaging host not found"

O registro do host nativo está ausente ou não corresponde ao ID da extensão. Na pasta mac-use, execute novamente o comando de registro com o ID atual de chrome://extensions. Depois, clique no ícone da extensão para conectar. Confira se .build/release/mac-use-mcp continua no mesmo caminho e se a extensão está carregada no perfil do Chrome que você está usando.

Privacidade e controle

A extensão do Chrome pode ler o texto das páginas e os valores dos formulários, exceto senhas. Ela pode clicar, preencher campos, digitar e rolar em abas que abriu. Ela não controla a aba selecionada; ao selecionar uma aba automatizada, você retoma o controle. Quando browser_close é chamado ou a extensão se desconecta, ela tenta fechar somente as abas que criou e que ainda aparentam estar inativas e não terem sido selecionadas pelo usuário. O Chrome não torna atômicas a verificação de atividade e a remoção da aba; portanto, uma seleção que coincida com a remoção ainda pode resultar no fechamento. O conteúdo e as capturas das páginas ficam visíveis para a sessão do Distill. Não use essas ferramentas em páginas com informações que você não queira compartilhar com essa sessão. A extensão solicita acesso a sites HTTP e HTTPS para poder operar nas páginas que você pedir para abrir.