Permet aux agents IA de voir et de piloter les applications macOS grâce à un accès structuré à l'interface utilisateur, des captures d'écran et l'OCR.
Aussi connu sous wende/macbeth
- Étoiles
- 4
- Outils
- —
- Téléchargements, 30 jours
- —
- Dernière version
- 0.2.4
- Dernier commit
- 20 sept. 2026
- Licence
- MIT
Qu'est-ce que Macbeth MCP ?
Macbeth est un serveur MCP. Permet aux agents IA de voir et de piloter les applications macOS grâce à un accès structuré à l'interface utilisateur, des captures d'écran et l'OCR.
Résumé généré à partir du README du projet
À propos du MCP server Macbeth
Macbeth fournit une couche de contrôle qui permet aux agents IA d'interagir avec les applications macOS en utilisant des données d'interface utilisateur structurées, des captures d'écran et l'OCR. Il fait office de pont pour permettre aux agents de voir et de piloter des interfaces natives ou basées sur Electron. Les développeurs peuvent l'intégrer via un MCP server local en stdio en utilisant npx ou via une API TypeScript dédiée. Le système est conçu pour fonctionner sur macOS 14 ou une version ultérieure et nécessite Node.js 20 ou une version supérieure.
Au lieu de se reposer uniquement sur des coordonnées visuelles, le serveur donne la priorité aux arbres d'accessibilité pour interroger les rôles, les étiquettes et les valeurs. Lorsque les métadonnées sont manquantes ou incomplètes, il utilise ScreenCaptureKit et Vision OCR pour interpréter l'écran. Il inclut des compétences intégrées pour des applications spécifiques comme Logic Pro, Réglages Système et Mail, ce qui aide les agents à naviguer dans des flux de travail complexes. Les utilisateurs doivent accorder les permissions d'accessibilité et d'enregistrement de l'écran pour activer toutes les capacités d'interaction.
Ce que vous pouvez faire avec
- 1Automatiser des logiciels de création complexesDonnez l'instruction à un agent d'ajuster les paramètres au sein d'outils audio professionnels comme Logic Pro.
- 2Gérer les configurations systèmeDemandez à une IA d'inspecter et de rendre compte de l'état actuel des réglages du pare-feu macOS.
- 3Extraire du texte de fenêtresUtilisez l'OCR pour extraire tout le texte visible d'une fenêtre d'application spécifique comme Notes.
- 4Piloter des applications ElectronNaviguez à travers des applications qui ne disposent pas d'une API standard en utilisant leurs interfaces exposées.
Extrait du README du projet. Chaque cas d'utilisation est vérifié par rapport à une citation du document.
Comment installer Macbeth MCP
Formats vérifiés le 10 nov. 2026Ajouter à CursorAjouter à GooseInstaller Macbeth MCP dans Claude Code
$ claude mcp add macbeth -- npx -y macbethInstaller Macbeth MCP dans Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"macbeth": {
"command": "npx",
"args": [
"-y",
"macbeth"
]
}
}
}Installer Macbeth MCP dans VS Code
.vscode/mcp.json
{
"servers": {
"macbeth": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"macbeth"
]
}
}
}Installer Macbeth MCP dans VS Code CLI
$ code --add-mcp '{"name":"macbeth","type":"stdio","command":"npx","args":["-y","macbeth"]}'Installer Macbeth MCP dans Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"macbeth": {
"command": "npx",
"args": [
"-y",
"macbeth"
]
}
}
}Installer Macbeth MCP dans Codex
$ codex mcp add macbeth -- npx -y macbethInstaller Macbeth MCP dans Codex config.toml
~/.codex/config.toml
[mcp_servers.macbeth] command = "npx" args = ["-y", "macbeth"]
Installer Macbeth MCP dans Gemini CLI
$ gemini mcp add -s user macbeth npx -- -y macbethInstaller Macbeth MCP dans Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"macbeth": {
"command": "npx",
"args": [
"-y",
"macbeth"
]
}
}
}Vérifications automatisées
Exécuté le 14 nov. 2026Rapport complet →A passé nos vérifications automatisées. Il ne s'agit pas d'un audit de sécurité : lisez le code et donnez au serveur l'accès le plus restreint dont il a besoin. Fonctionnement des vérifications
- Dépôt source lié et accessiblewende/macbeth is public and reachablegithub.com/wende/macbeth ↗Réussi
- Le nom du package correspond au dépôt sourcemacbeth names wende/macbeth as sourcenpmjs.com/package/macbeth ↗Réussi
- Provenance du build (attestation Sigstore)Sigstore attestation for macbethnpmjs.com/package/macbeth/v/0.2.4#provenance ↗Réussi
- Licence open source (OSI)MITspdx.org/licenses/MIT.html ↗Réussi
- Commit ou version publiée au cours de l'année écouléeLast commit or release 2026-09-20github.com/wende/macbeth ↗Réussi
- OpenSSF ScorecardNon vérifié
- Nom du package non proche d'un package populaireNo popular package one edit away from macbethRéussi
- Aucun avis critique dans le package ou ses dépendances99 resolved dependencies checked; no critical advisoryosv.dev ↗Réussi
- Aucune instruction cachée destinée au modèle0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersRéussi
- Les outils destructifs sont étiquetésNon vérifié
- Le point de terminaison distant répond à la poignée de main MCPNon vérifié
README
Voir sur GitHubQuickstart
Give Claude Code access to Macbeth:
claude mcp add macbeth -- npx -y macbeth
Then ask it to verify the connection:
Using Macbeth, list the running applications, connect to Finder, inspect its front window, and summarize the first few controls you can see. Do not perform any other actions.
Macbeth ships with a prebuilt, signed and notarized universal daemon. No Swift toolchain or manual service installation is required. If setup fails, run npx macbeth doctor; it prints a self-contained diagnostic prompt you can paste back into your agent.
Any MCP client that can launch a stdio server can use npx -y macbeth. See MCP setup for generic configuration, updates, and the complete tool list.
Add Macbeth as an MCP server using
npx -y macbeth. Runnpx macbeth doctor, guide me through granting only the permissions I need, and verify the setup by inspecting Finder. Do not take any unrelated actions.
Across your Mac
Work inside Unity, Logic Pro, and other complex tools
“In Logic Pro, set the project tempo to 128 BPM and start playback.”
Macbeth combines structured controls, menus, keyboard input, screenshots, OCR, and application-specific guidance. Logic Pro has a dedicated skill. Applications with thinner accessibility trees, including parts of Unity, can combine structured controls with keyboard, menu, screenshot, and OCR fallbacks.
Automate macOS itself
“Open System Settings, find the firewall controls, and report their current state without changing anything.”
Macbeth can inspect named controls and values, select native menu items, and use keyboard input when a semantic action is unavailable.
Use applications even when they have no API
“Open HEY, find the newest visible thread from the design team, and summarize it without sending or changing anything.”
Macbeth can work through exposed Electron interfaces even when the service does not provide the API your agent needs. HEY works through Macbeth's generic Electron support; results vary with the application's accessibility tree and version.
See what the accessibility tree misses
“Capture the frontmost Notes window and extract all visible text.”
ScreenCaptureKit screenshots and local Vision OCR provide a fallback for content that macOS does not expose as useful accessibility data.
Build repeatable scripts and tests
The same engine is available as a TypeScript API with lazy locators, auto-waiting actions, explicit state waits, screenshots, and application connections.
[!IMPORTANT] Macbeth can act inside applications on your behalf. Connect only trusted agents and require approval for consequential actions.
Why Macbeth?
- Use your own agent. Macbeth is a control layer, not a model or agent runtime.
- Structured when possible. Query roles, labels, values, enabled state, hierarchy, and stable handles instead of relying only on coordinates.
- Visual when necessary. Fall back to window capture and OCR when accessibility metadata is thin.
- Application-aware. Versioned skills preserve workflows, shortcuts, and known failure modes.
- Scriptable. Use the same primitives interactively over MCP or directly from TypeScript.
Structured before pixels
| Capability | Typical screenshot-driven agent | Macbeth |
|---|---|---|
| Find a labeled control | Visual inference | Accessibility query when exposed |
| Read role, value, and state | Inferred | Structured attributes |
| Wait for a UI change | Usually observed through repeated captures | Explicit waits and auto-waiting actions |
| Handle incomplete UI metadata | Vision/OCR | Accessibility first, screenshot/OCR fallback |
| Reuse application knowledge | Prompt-dependent | Bundled, versioned skills |
Accessibility information can itself be incomplete or misleading. Macbeth is a hybrid interface: it uses stronger structured primitives when macOS exposes them and keeps visual and system-level fallbacks available when it does not.
Security and limitations
- Macbeth requires macOS 14 or newer and Node.js 20 or newer.
- Accessibility permission is required for UI inspection and interaction. Screen Recording is required only for screenshots and window OCR.
- Application accessibility quality varies. Custom-rendered canvases, games, and some creative tools may require menus, screenshots, OCR, keyboard input, or application-specific guidance.
- Interface changes between application versions can break specialized workflows.
- The interaction glow makes Macbeth activity visible, but it is not an approval system or a complete audit log.
- Agents can make mistakes. Use human review for destructive, financial, publishing, or privacy-sensitive actions.
Macbeth uses a local stdio MCP server and a Unix-domain socket; it does not open a TCP listener. Screenshots requested through MCP are written to a temporary directory and are not automatically deleted. Read the security model for data flow, permission revocation, local-process risks, and safer operating practices.
TypeScript API
npm install macbeth
import { connect } from "macbeth";
const app = await connect("TextEdit");
await app.window("Untitled").textField().fill("Hello from Macbeth");
await app.pressKey("s", ["cmd"]);
See Developing with Macbeth for locators, screenshots, Electron behavior, lifecycle, and tests.
Teach Macbeth an application
A Macbeth skill is a SKILL.md file, optionally accompanied by runnable scripts, that teaches an agent reliable workflows and pitfalls. Call load_skill with no arguments for the core Macbeth guide. Bundled app skills cover Calendar, Contacts, Logic Pro, Mail, Maps, Messages, Music, Notes, Reminders, Safari, System Settings, and generic Electron applications.
You can add a skill without changing the Swift daemon. Start with the contribution guide and include a reproducible prompt, tested application version, expected result, and honest failure modes.
Documentation
| Guide | Contents |
|---|---|
| MCP server | Installation, smoke test, tools, skills, and updates |
| CLI | Every MCP tool as a macbeth <tool> subcommand |
| TypeScript API | Client API, locators, Electron, and tests |
| Architecture | Daemon, protocol, fallbacks, and design notes |
| Security | Trust boundaries, data handling, and permission revocation |
| Troubleshooting | Diagnostics and common setup failures |
| Contributing | Development workflow and application skills |
Requirements
- macOS 14 (Sonoma) or later
- Node.js 20+
- Swift 6.0+ only when building the daemon from source
License
MIT
Questions sur Macbeth MCP
Comment ajouter Macbeth MCP à Claude Code ?
Exécutez claude mcp add macbeth -- npx -y macbeth dans votre terminal. Ajoutez --scope user pour le rendre disponible dans tous les projets.
Comment ajouter Macbeth MCP à Cursor ?
Ouvrez ~/.cursor/mcp.json et ajoutez le serveur sous mcpServers, avec la configuration Cursor indiquée dans la section d'installation ci-dessus.
Quels sont les prérequis système pour Macbeth ?
Macbeth nécessite macOS 14 (Sonoma) ou une version ultérieure, ainsi que Node.js 20 ou une version ultérieure.
Comment ajouter Macbeth à Claude Code ?
Vous pouvez l'ajouter en utilisant la commande : claude mcp add macbeth -- npx -y macbeth.
Macbeth nécessite-t-il des permissions spéciales ?
Oui, l'autorisation d'Accessibilité est requise pour l'inspection et l'interaction avec l'interface utilisateur, et l'autorisation d'Enregistrement de l'écran est nécessaire pour les captures d'écran et l'OCR des fenêtres.
Macbeth peut-il fonctionner avec des applications qui n'ont pas d'API ?
Oui, il peut fonctionner via les interfaces Electron exposées et utiliser des solutions de repli visuelles comme les captures d'écran et l'OCR lorsque les métadonnées d'accessibilité sont indisponibles.