macos-control-mcp 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pierre Haddad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,396 @@
+# macos-control-mcp
+
+Give AI agents **eyes and hands** on macOS.
+
+[![npm](https://img.shields.io/npm/v/macos-control-mcp)](https://www.npmjs.com/package/macos-control-mcp)
+[![license](https://img.shields.io/npm/l/macos-control-mcp)](./LICENSE)
+![macOS](https://img.shields.io/badge/macOS-13%2B-blue)
+
+## What is this?
+
+An [MCP server](https://modelcontextprotocol.io) that lets AI agents **see your screen, read text on it, and interact** — click, type, scroll — just like a human sitting at the keyboard. Unlike blind script runners, this MCP gives agents _state awareness_: they screenshot the screen, OCR it to get text with pixel coordinates, then click exactly where they need to.
+
+## The See-Think-Act Loop
+
+```
+┌─────────────────────────────────────────────────┐
+│                                                 │
+│   1. SEE        screenshot / screen_ocr         │
+│      ↓          "What's on the screen?"         │
+│                                                 │
+│   2. THINK      AI reasons about the content    │
+│      ↓          "I need to click the Save btn"  │
+│                                                 │
+│   3. ACT        click_at / type_text / press_key│
+│                 "Click at (425, 300)"           │
+│                                                 │
+│      ↻ repeat                                   │
+└─────────────────────────────────────────────────┘
+```
+
+This is what makes it powerful: the agent _sees_ the result of every action and can course-correct, retry, or move on — just like you would.
+
+## Quick Start
+
+No install needed — run directly with npx:
+
+```bash
+npx -y macos-control-mcp
+```
+
+On first run, a Python virtual environment is automatically created at `~/.macos-control-mcp/.venv` with the required Apple Vision and Quartz frameworks. This takes ~60 seconds once and persists across updates.
+
+## Configure Your AI Client
+
+All clients use the same command: `npx -y macos-control-mcp`
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "macos-control": {
+      "command": "npx",
+      "args": ["-y", "macos-control-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+</details>
+
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+```bash
+claude mcp add macos-control -- npx -y macos-control-mcp
+```
+</details>
+
+<details>
+<summary><strong>VS Code / GitHub Copilot</strong></summary>
+
+Add to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "macos-control": {
+      "command": "npx",
+      "args": ["-y", "macos-control-mcp"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "macos-control": {
+      "command": "npx",
+      "args": ["-y", "macos-control-mcp"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Cline</strong></summary>
+
+Open Cline extension settings → MCP Servers → Add:
+
+```json
+{
+  "macos-control": {
+    "command": "npx",
+    "args": ["-y", "macos-control-mcp"]
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Windsurf</strong></summary>
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "macos-control": {
+      "command": "npx",
+      "args": ["-y", "macos-control-mcp"]
+    }
+  }
+}
+```
+</details>
+
+## Permissions
+
+macOS requires two permissions for full functionality:
+
+1. **Screen Recording** — for screenshots and OCR
+2. **Accessibility** — for clicking, typing, and reading UI elements
+
+Go to **System Settings → Privacy & Security** and add your terminal app (Terminal, iTerm2, VS Code, etc.) to both lists. You'll be prompted on first use.
+
+## Tools (15)
+
+### See the screen
+
+| Tool | Description |
+|---|---|
+| `screenshot` | Capture full screen or app window as PNG |
+| `screen_ocr` | OCR the screen — returns text elements with pixel coordinates |
+| `find_text_on_screen` | Find specific text and get clickable x,y coordinates |
+
+### Interact with the screen
+
+| Tool | Description |
+|---|---|
+| `click_at` | Click at x,y coordinates (returns screenshot) |
+| `double_click_at` | Double-click at x,y (returns screenshot) |
+| `type_text` | Type text into the frontmost app |
+| `press_key` | Press key combos (Cmd+S, Ctrl+C, etc.) |
+| `scroll` | Scroll up/down/left/right |
+
+### App management
+
+| Tool | Description |
+|---|---|
+| `launch_app` | Open or focus an application |
+| `list_running_apps` | List visible running apps |
+
+### Accessibility tree
+
+| Tool | Description |
+|---|---|
+| `get_ui_elements` | Get accessibility tree of an app window |
+| `click_element` | Click a named UI element (returns screenshot) |
+
+### Utilities
+
+| Tool | Description |
+|---|---|
+| `open_url` | Open URL in Safari or Chrome |
+| `get_clipboard` | Read clipboard contents |
+| `set_clipboard` | Write to clipboard |
+
+## Example Workflows
+
+### Fill out a web form
+
+```
+You: "Go to example.com/signup and fill in my details"
+
+Agent:
+1. open_url("https://example.com/signup")
+2. screenshot() → sees the form
+3. screen_ocr() → finds "Email" field at (300, 250)
+4. click_at(300, 250) → clicks the email field
+5. type_text("user@example.com")
+6. find_text_on_screen("Submit") → gets button coordinates
+7. click_at(350, 500) → submits the form
+8. screenshot() → confirms success
+```
+
+### Navigate an unfamiliar app
+
+```
+You: "Change the font size to 16 in TextEdit"
+
+Agent:
+1. launch_app("TextEdit")
+2. screenshot() → sees the app
+3. get_ui_elements("TextEdit") → finds menu items
+4. press_key("t", ["command"]) → opens Fonts panel
+5. screenshot() → sees the font panel
+6. find_text_on_screen("Size") → locates the size field
+7. click_at(x, y) → clicks size field
+8. type_text("16")
+9. press_key("return")
+```
+
+### Extract info from an email
+
+```
+You: "Copy the tracking number from the shipping email in Mail"
+
+Agent:
+1. launch_app("Mail")
+2. screenshot() → sees the inbox
+3. find_text_on_screen("Your order has shipped") → locates the email
+4. click_at(x, y) → opens the email
+5. screenshot() → sees the email content
+6. screen_ocr() → extracts all text including tracking number
+7. set_clipboard("1Z999AA10123456784") → copies to clipboard
+```
+
+### Take a screenshot and describe what's on screen
+
+```
+You: "What do I have open right now?"
+
+Agent:
+1. screenshot() → captures the full screen
+2. Describes what it sees: apps, windows, content
+3. list_running_apps() → ["Safari", "Slack", "VS Code", "Spotify"]
+4. "You have Safari open on Twitter, Slack with 3 unread messages, and VS Code editing index.ts"
+```
+
+### Debug a UI issue
+
+```
+You: "The submit button on this page isn't working, can you check what's happening?"
+
+Agent:
+1. screenshot() → sees the page
+2. find_text_on_screen("Submit") → locates button at (500, 600)
+3. get_ui_elements("Safari") → inspects accessibility tree
+4. "The button has aria-disabled=true. There's a required field 'Phone' that's empty."
+5. find_text_on_screen("Phone") → locates the field
+6. click_at(x, y) → clicks the field
+7. type_text("+1 555-0123")
+8. click_at(500, 600) → clicks Submit again
+9. screenshot() → confirms it worked
+```
+
+### Control Spotify
+
+```
+You: "Pause the music and turn the volume down"
+
+Agent:
+1. launch_app("Spotify")
+2. screenshot() → sees Spotify is playing
+3. find_text_on_screen("Pause") → locates pause button
+4. click_at(x, y) → pauses playback
+5. find_text_on_screen("Volume") → locates volume slider area
+6. click_at(x, y) → adjusts volume
+7. screenshot() → confirms paused and volume lowered
+```
+
+### Work with Finder
+
+```
+You: "Create a new folder on my Desktop called 'Project Assets' and move it to Documents"
+
+Agent:
+1. launch_app("Finder")
+2. press_key("d", ["command", "shift"]) → opens Desktop
+3. screenshot() → sees Desktop in Finder
+4. press_key("n", ["command", "shift"]) → creates new folder
+5. type_text("Project Assets")
+6. press_key("return")
+7. screenshot() → confirms folder created
+```
+
+### Send a message in Slack
+
+```
+You: "Send 'build is green, ready to deploy' in the #engineering channel on Slack"
+
+Agent:
+1. launch_app("Slack")
+2. screenshot() → sees Slack
+3. press_key("k", ["command"]) → opens Quick Switcher
+4. type_text("engineering")
+5. press_key("return") → opens #engineering
+6. screenshot() → confirms channel is open
+7. click_at(x, y) → clicks message input
+8. type_text("build is green, ready to deploy")
+9. press_key("return") → sends message
+10. screenshot() → confirms sent
+```
+
+### Research and copy data from a website
+
+```
+You: "Look up the current price of AAPL on Google Finance and copy it"
+
+Agent:
+1. open_url("https://google.com/finance/quote/AAPL:NASDAQ")
+2. screenshot() → sees the page loading
+3. screen_ocr() → reads all text on the page
+4. Finds the price: "$187.42"
+5. set_clipboard("$187.42")
+6. "Copied AAPL price $187.42 to your clipboard"
+```
+
+### Multi-app workflow
+
+```
+You: "Take what's in my clipboard, search for it in Safari, and screenshot the results"
+
+Agent:
+1. get_clipboard() → "best mechanical keyboards 2025"
+2. launch_app("Safari")
+3. press_key("l", ["command"]) → focuses address bar
+4. type_text("best mechanical keyboards 2025")
+5. press_key("return") → searches
+6. screenshot() → captures the search results
+7. "Here are the search results for 'best mechanical keyboards 2025'"
+```
+
+### Navigate System Settings
+
+```
+You: "Turn on Dark Mode"
+
+Agent:
+1. launch_app("System Settings")
+2. screenshot() → sees System Settings
+3. find_text_on_screen("Appearance") → locates the option
+4. click_at(x, y) → opens Appearance settings
+5. screenshot() → sees Light/Dark/Auto options
+6. find_text_on_screen("Dark") → locates Dark mode option
+7. click_at(x, y) → enables Dark Mode
+8. screenshot() → confirms Dark Mode is on
+```
+
+## Requirements
+
+- **macOS 13+** (Ventura or later)
+- **Node.js 18+**
+- **Python 3.9+** (pre-installed on macOS — needed for OCR and mouse control)
+
+## How It Works
+
+- **Screenshots** — native `screencapture` CLI
+- **OCR** — Apple Vision framework (VNRecognizeTextRequest) via Python bridge, returns text with bounding box coordinates
+- **Mouse** — Quartz Core Graphics events via Python bridge for precise pixel-level control
+- **Keyboard & Apps** — AppleScript via `osascript` for key presses, app launching, and UI element interaction
+- **Python env** — auto-managed venv at `~/.macos-control-mcp/.venv/` with only two packages (`pyobjc-framework-Vision`, `pyobjc-framework-Quartz`)
+
+## Troubleshooting
+
+**"Permission denied" or blank screenshots**
+→ Add your terminal to System Settings → Privacy & Security → Screen Recording
+
+**Clicks don't work**
+→ Add your terminal to System Settings → Privacy & Security → Accessibility
+
+**Python setup fails**
+→ Ensure `python3` is in your PATH. Run `python3 --version` to check. Non-Python tools (keyboard, apps, clipboard) still work without it.
+
+**OCR returns empty results**
+→ Make sure Screen Recording permission is granted. Try a full-screen OCR first (without the `app` parameter).
+
+**"App not found" errors**
+→ Use the exact app name as shown in Activity Monitor (e.g., "Google Chrome" not "Chrome").
+
+## License
+
+[MIT](./LICENSE)

package/build/src/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/src/index.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { getScreenState } from "./tools/screen.js";
+import { screenOCR, findTextOnScreen } from "./tools/ocr.js";
+import { clickAt, doubleClickAt, scroll } from "./tools/mouse.js";
+import { typeText, pressKey } from "./tools/input.js";
+import { launchApp, listRunningApps } from "./tools/apps.js";
+import { getUIElements, clickElement } from "./tools/ui.js";
+import { openUrl } from "./tools/browser.js";
+import { getClipboard, setClipboard } from "./tools/clipboard.js";
+import { ensurePythonVenv } from "./utils/python.js";
+const server = new McpServer({
+    name: "macos-control",
+    version: "0.0.1",
+});
+// ── See the screen ──────────────────────────────────────────────
+server.tool("screenshot", "Capture a screenshot of the entire screen or a specific app window. Returns a PNG image.", { app: z.string().optional().describe("App name to capture. Omit for full screen.") }, async ({ app }) => {
+    try {
+        const { base64, mimeType } = await getScreenState(app);
+        return { content: [{ type: "image", data: base64, mimeType }] };
+    }
+    catch (err) {
+        return { isError: true, content: [{ type: "text", text: String(err) }] };
+    }
+});
+server.tool("screen_ocr", "OCR the screen using Apple Vision. Returns every text element with pixel coordinates (x, y, centerX, centerY). Use centerX/centerY with click_at to click on any text.", { app: z.string().optional().describe("App to OCR. Omit for full screen.") }, async ({ app }) => {
+    try {
+        const result = await screenOCR(app);
+        return { content: [{ type: "text", text: result }] };
+    }
+    catch (err) {
+        return { isError: true, content: [{ type: "text", text: String(err) }] };
+    }
+});
+server.tool("find_text_on_screen", "Find specific text on screen and get its clickable coordinates. Like Ctrl+F for the entire screen. Returns matches with centerX/centerY for use with click_at.", {
+    text: z.string().describe("Text to find (case-insensitive)"),
+    app: z.string().optional().describe("App to search in. Omit for full screen."),
+}, async ({ text, app }) => {
+    try {
+        const result = await findTextOnScreen(text, app);
+        return { content: [{ type: "text", text: result }] };
+    }
+    catch (err) {
+        return { isError: true, content: [{ type: "text", text: String(err) }] };
+    }
+});
+// ── Interact with the screen ────────────────────────────────────
+server.tool("click_at", "Click at x,y screen coordinates. Returns a screenshot after clicking. Use screenshot + screen_ocr to find coordinates first.", {
+    x: z.number().describe("X coordinate"),
+    y: z.number().describe("Y coordinate"),
+}, async ({ x, y }) => {
+    try {
+        const { text, screenshot } = await clickAt(x, y);
+        return {
+            content: [
+                { type: "text", text },
+                { type: "image", data: screenshot.base64, mimeType: screenshot.mimeType },
+            ],
+        };
+    }
+    catch (err) {
+        return { isError: true, content: [{ type: "text", text: String(err) }] };
+    }
+});
+server.tool("double_click_at", "Double-click at x,y screen coordinates. Returns a screenshot after clicking.", {
+    x: z.number().describe("X coordinate"),
+    y: z.number().describe("Y coordinate"),
+}, async ({ x, y }) => {
+    try {
+        const { text, screenshot } = await doubleClickAt(x, y);
+        return {
+            content: [
+                { type: "text", text },
+                { type: "image", data: screenshot.base64, mimeType: screenshot.mimeType },
+            ],
+        };
+    }
+    catch (err) {
+        return { isError: true, content: [{ type: "text", text: String(err) }] };
+    }
+});
+server.tool("type_text", "Type text into the frontmost app using keyboard input.", { text: z.string().describe("Text to type") }, async ({ text }) => {
+    try {
+        const result = await typeText(text);
+        return { content: [{ type: "text", text: result }] };
+    }
+    catch (err) {
+        return { isError: true, content: [{ type: "text", text: String(err) }] };
+    }
+});
+server.tool("press_key", "Press a key combo (e.g. press 's' with ['command'] for Cmd+S). Supports a-z, 0-9, return, tab, space, delete, escape, arrows, f1-f12.", {
+    key: z.string().describe("Key name: a-z, 0-9, return, tab, space, delete, escape, up/down/left/right, f1-f12"),
+    modifiers: z
+        .array(z.string())
+        .optional()
+        .describe("Modifier keys: 'command', 'shift', 'option', 'control'"),
+}, async ({ key, modifiers }) => {
+    try {
+        const result = await pressKey(key, modifiers);
+        return { content: [{ type: "text", text: result }] };
+    }
+    catch (err) {
+        return { isError: true, content: [{ type: "text", text: String(err) }] };
+    }
+});
+server.tool("scroll", "Scroll in the frontmost application.", {
+    direction: z.enum(["up", "down", "left", "right"]).describe("Scroll direction"),
+    amount: z.number().default(3).describe("Number of lines to scroll (default 3)"),
+}, async ({ direction, amount }) => {
+    try {
+        const result = await scroll(direction, amount);
+        return { content: [{ type: "text", text: result }] };
+    }
+    catch (err) {
+        return { isError: true, content: [{ type: "text", text: String(err) }] };
+    }
+});
+// ── App management ──────────────────────────────────────────────
+server.tool("launch_app", "Open or focus a macOS application by name.", { name: z.string().describe("Application name, e.g. 'Safari', 'Notes'") }, async ({ name }) => {
+    try {
+        const text = await launchApp(name);
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        return { isError: true, content: [{ type: "text", text: String(err) }] };
+    }
+});
+server.tool("list_running_apps", "List all visible running macOS applications.", async () => {
+    try {
+        const text = await listRunningApps();
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        return { isError: true, content: [{ type: "text", text: String(err) }] };
+    }
+});
+// ── Accessibility tree ──────────────────────────────────────────
+server.tool("get_ui_elements", "Get the accessibility tree of an app window. Returns UI element roles, names, and positions.", { app: z.string().describe("Application process name") }, async ({ app }) => {
+    try {
+        const text = await getUIElements(app);
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        return { isError: true, content: [{ type: "text", text: String(err) }] };
+    }
+});
+server.tool("click_element", "Click a named UI element in an app window. Returns a screenshot after clicking. Use get_ui_elements to discover element names.", {
+    app: z.string().describe("Application process name"),
+    name: z.string().describe("Name of the UI element to click"),
+}, async ({ app, name }) => {
+    try {
+        const { text, screenshot } = await clickElement(app, name);
+        return {
+            content: [
+                { type: "text", text },
+                { type: "image", data: screenshot.base64, mimeType: screenshot.mimeType },
+            ],
+        };
+    }
+    catch (err) {
+        return { isError: true, content: [{ type: "text", text: String(err) }] };
+    }
+});
+// ── Utilities ───────────────────────────────────────────────────
+server.tool("open_url", "Open a URL in Safari or Chrome.", {
+    url: z.string().describe("URL to open"),
+    browser: z.string().optional().describe("'safari' or 'chrome' (defaults to Safari)"),
+}, async ({ url, browser }) => {
+    try {
+        const result = await openUrl(url, browser);
+        return { content: [{ type: "text", text: result }] };
+    }
+    catch (err) {
+        return { isError: true, content: [{ type: "text", text: String(err) }] };
+    }
+});
+server.tool("get_clipboard", "Read the current text contents of the macOS clipboard.", async () => {
+    try {
+        const text = await getClipboard();
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        return { isError: true, content: [{ type: "text", text: String(err) }] };
+    }
+});
+server.tool("set_clipboard", "Write text to the macOS clipboard.", { text: z.string().describe("Text to copy to clipboard") }, async ({ text }) => {
+    try {
+        const result = await setClipboard(text);
+        return { content: [{ type: "text", text: result }] };
+    }
+    catch (err) {
+        return { isError: true, content: [{ type: "text", text: String(err) }] };
+    }
+});
+// ── Start server ────────────────────────────────────────────────
+async function main() {
+    await ensurePythonVenv();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/build/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/build/src/tools/apps.d.ts

@@ -0,0 +1,4 @@
+export declare function launchApp(name: string): Promise<string>;
+export declare function quitApp(name: string): Promise<string>;
+export declare function focusApp(name: string): Promise<string>;
+export declare function listRunningApps(): Promise<string>;

package/build/src/tools/apps.js

@@ -0,0 +1,27 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { runAppleScript, escapeForAppleScript } from "../utils/applescript.js";
+const execFileAsync = promisify(execFile);
+async function openApp(name) {
+    await execFileAsync("open", ["-a", name]);
+}
+export async function launchApp(name) {
+    await openApp(name);
+    return `Launched "${name}".`;
+}
+export async function quitApp(name) {
+    const safe = escapeForAppleScript(name);
+    await runAppleScript(`tell application "${safe}" to quit`);
+    return `Quit "${name}".`;
+}
+export async function focusApp(name) {
+    await openApp(name);
+    return `Focused "${name}".`;
+}
+export async function listRunningApps() {
+    const raw = await runAppleScript(`tell application "System Events" to get name of every application process whose background only is false`);
+    // AppleScript returns comma-separated list
+    const apps = raw.split(", ").map((s) => s.trim()).filter(Boolean);
+    return JSON.stringify(apps, null, 2);
+}
+//# sourceMappingURL=apps.js.map