# One-command global install (recommended)
uv tool install macos-computer-use-mcp

# Or run without installing (like npx)
uvx macos-computer-use-mcp

# Check permissions
python -c "from computer_use_mcp.darwin.tcc import check_all; print(check_all().report())"

# List all 146 tools
python -c "
import asyncio
from computer_use_mcp.server import mcp
async def main():
    tools = await mcp.list_tools()
    print(f'{len(tools)} tools registered')
asyncio.run(main())
"

{
  "mcpServers": {
    "macos-computer-use": {
      "command": "macos-computer-use-mcp"
    }
  }
}

{
  "mcpServers": {
    "macos-computer-use": {
      "command": "uvx",
      "args": ["macos-computer-use-mcp"]
    }
  }
}

{
  "mcpServers": {
    "macos-computer-use": {
      "command": "macos-computer-use-mcp"
    }
  }
}

npx @anthropic-ai/mcp-inspector python -m computer_use_mcp

# Pick one provider, set the key in ~/.zshrc:
export OPENAI_API_KEY="sk-..."        # gpt-4o — https://platform.openai.com/api-keys
export ANTHROPIC_API_KEY="sk-ant-..." # claude-sonnet-5 — https://console.anthropic.com
export ZHIPU_API_KEY="..."            # glm-4v — https://open.bigmodel.cn

# agent.py — minimal agent loop
import asyncio, base64, json, os
from openai import OpenAI
from mcp.client import ClientSession
from mcp.client.stdio import stdio_client, StdioServerParameters

async def main():
    goal = input("🎯 What should I do? ")
    server = StdioServerParameters(command="macos-computer-use-mcp")
    client = OpenAI()  # reads OPENAI_API_KEY from env

    async with stdio_client(server) as (read, write):
        async with ClientSession(read, write) as session:
            messages = [{"role": "system", "content": "You control a Mac desktop. Reply with JSON: {\"tool\": \"...\", \"args\": {...}} or {\"done\": true}."}]

            for step in range(15):
                # Screenshot → model decides → execute
                result = await session.call_tool("screenshot", {})
                img = result.content[0].data

                response = client.chat.completions.create(
                    model=os.getenv("MODEL", "gpt-4o"),
                    messages=messages + [{"role": "user", "content": [
                        {"type": "text", "text": f"Step {step+1}. Goal: {goal}"},
                        {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{img}"}}
                    ]}],
                )
                action = json.loads(response.choices[0].message.content.strip().removeprefix("```json").removesuffix("```"))
                if action.get("done"):
                    break
                await session.call_tool(action["tool"], action.get("args", {}))
                messages.append({"role": "assistant", "content": json.dumps(action)})

    print("✅ Done!")

asyncio.run(main())

# screenshot → OCR → text model
ocr = await session.call_tool("ocr_screenshot", {})
response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": "You control a Mac desktop. Reply with JSON tool calls."},
        {"role": "user", "content": f"Screen contents:\n{ocr}\n\nGoal: {goal}"}
    ]
)

# Required env vars:
export DEEPSEEK_API_KEY="sk-..."  # https://platform.deepseek.com/api_keys

from langchain_mcp import MCPToolkit
toolkit = MCPToolkit(command="macos-computer-use-mcp")
tools = await toolkit.get_tools()

// .mcp.json at project root
{
  "mcpServers": {
    "macos-computer-use": {
      "command": "macos-computer-use-mcp"
    }
  }
}

┌────────────────────────────────────────────────────────────┐
│ L3: App Semantics (68 tools)                                │
│ Calendar · Reminders · Notes · Mail · Messages · Contacts   │
│ Finder · Safari · Music · Shortcuts · Settings              │
├────────────────────────────────────────────────────────────┤
│ L2: Deterministic Tools (54 tools)                          │
│ Window Mgmt · App Lifecycle · AX Tree · OCR · Clipboard     │
│ File System · System Info · Battery · WiFi · Bluetooth      │
├────────────────────────────────────────────────────────────┤
│ L1: OS Primitives (24 tools)                                │
│ Screenshot · Mouse · Keyboard · Cursor · Input Source       │
│ Timing · Display                                            │
└────────────────────────────────────────────────────────────┘

src/computer_use_mcp/
├── server.py              # MCP entry point (stdio transport)
├── __init__.py            # Version, package metadata
│
├── darwin/                # macOS-specific implementations (no MCP dependency)
│   ├── cg_screen.py       #   CGDisplay / CGImage screenshot capture
│   ├── cg_input.py        #   CGEvent mouse + keyboard injection
│   ├── cg_keyboard.py     #   Text synthesis + key-code mapping
│   ├── ax_window.py       #   CGWindowList + AXUIElement window ops
│   ├── ax_tree.py         #   Accessibility tree walker (200+ lines)
│   ├── clipboard.py       #   pbcopy/pbpaste + NSImage clipboard
│   ├── ocr.py             #   VNRecognizeTextRequest (Vision framework)
│   ├── file_ops.py        #   Pure-Python pathlib/shutil file operations
│   ├── tcc.py             #   TCC permission checker (tccutil + osascript)
│   ├── system.py          #   IOKit brightness, pmset, networksetup, etc.
│   ├── calendar.py        #   Calendar.app AppleScript
│   ├── reminders.py       #   Reminders.app AppleScript
│   ├── notes.py           #   Notes.app AppleScript
│   ├── mail.py            #   Mail.app AppleScript
│   ├── messages.py        #   Messages.app AppleScript
│   ├── contacts.py        #   Contacts.app AppleScript
│   ├── finder.py          #   Finder.app AppleScript
│   ├── safari.py          #   Safari.app AppleScript
│   ├── music.py           #   Music.app AppleScript
│   ├── shortcuts.py       #   Shortcuts CLI + AppleScript
│   └── settings.py        #   System Settings + defaults CLI
│
├── tools/                 # MCP tool registration layer (thin wrappers)
│   ├── screen.py          #   @mcp.tool() async def screenshot()
│   ├── mouse.py           #   ... 21 more modules
│   ├── cursor.py          #   (each module has a register(mcp) entry point)
│   ├── keyboard.py
│   ├── input_source.py
│   ├── timing.py
│   ├── window.py
│   ├── app.py
│   ├── ax_tree.py
│   ├── ocr.py
│   ├── clipboard.py
│   ├── file.py
│   ├── system.py
│   ├── calendar.py
│   ├── reminders.py
│   ├── notes.py
│   ├── mail.py
│   ├── messages.py
│   ├── contacts.py
│   ├── finder.py
│   ├── safari.py
│   ├── music.py
│   ├── shortcuts.py
│   └── settings.py
│
└── tests/                 # One test file per domain (30+ files)
    ├── test_server.py     #   Verifies all 146 tools are registered
    ├── test_screen.py
    ├── test_mouse.py
    └── ... (28 more)

# In your agent's tool-calling loop:
screenshot = await client.call_tool("screenshot")
# Feed to vision model...

text = await client.call_tool("ocr_find_text", {"text": "Submit"})
if text["found"]:
    x, y = text["bounds"]["x"] + text["bounds"]["w"] // 2
    text["bounds"]["y"] + text["bounds"]["h"] // 2
    await client.call_tool("mouse_move", {"x": x, "y": y})
    await client.call_tool("mouse_click", {})

await client.call_tool("safari_open_url", {"url": "https://github.com"})
await client.call_tool("safari_search", {"query": "macOS automation"})
tabs = await client.call_tool("safari_list_tabs")
# → {"tabs": [{"title": "...", "url": "...", ...}], "count": 5}

from mcp.client import ClientSession

async with ClientSession(stdio_transport) as session:
    while True:
        # 1. See the screen
        screen = await session.call_tool("screenshot")

        # 2. Vision model decides the next action
        action = vision_model.decide(screen, goal)

        # 3. Execute with MCP tools
        result = await session.call_tool(action.tool, action.params)

        # 4. Verify
        if action.done:
            break

# Clone for development
git clone https://github.com/yyyyyyyyiiiii/macos-computer-use-mcp.git
cd macos-computer-use-mcp
uv sync --all-extras

# Lint
uv run ruff check src tests

# Run all tests (requires macOS + permissions)
uv run pytest -q

# Run a subset
uv run pytest tests/test_server.py tests/test_safari.py -v

# Start the server locally (dev mode)
uv run python -m computer_use_mcp

# Get screen text as structured data
ocr = await session.call_tool("ocr_screenshot", {})
# Append OCR results to your model prompt for better grounding
prompt = f"Screen text visible:\n{ocr['text']}\n\nGoal: {goal}"