# mcp-osascript

Automates macOS with 18 typed tools for window tiling, menu clicks, clipboard reads, and browser tab queries. Ideal for giving AI direct control over the desktop.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 12
- Author: m0rvayne
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/m0rvayne/mcp-osascript
- Updated: 2026-09-11
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-osascript

## What it does

The server equips your assistant with 18 typed tools powered by AppleScript and JXA. It handles window placement, key presses, simulated typing up to 500 characters, window screenshots, and running Apple Shortcuts. If a requested menu item is missing, the server returns the valid entries at that menu level so the model corrects its own call automatically.

Running the package requires macOS 13+ and Node 18+. Without macOS Accessibility, Automation, and Screen Recording permissions granted to your terminal or host client, tools that manage windows or capture pixels will fail immediately. The process isolates environment variables strictly to `PATH`, `HOME`, and `LANG`, alongside a URL scheme allowlist restricted to `http`, `https`, and `mailto`.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add mcp-osascript -- npx -y mcp-osascript
```

### Codex

**Platform CLI**
```bash
codex mcp add mcp-osascript -- npx -y mcp-osascript
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "mcp-osascript": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-osascript"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "mcp-osascript": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "mcp-osascript"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add mcp-osascript npx -y mcp-osascript
```

## When to use it
- reposition and resize application windows across displays
- inspect active tab titles and URLs in Safari, Chrome, or Arc
- trigger nested menu bar items inside native desktop apps
- capture screenshots of a specific window instead of the full screen
- execute system Shortcuts directly by name

## Example prompts
- Grab a screenshot of the active browser window and save it to my Desktop
- List the titles and URLs of all tabs currently open in Arc
- Trigger the export command under the File menu in Keynote

## Similar
- [applescript](https://affpapa.org/en/nevibecode/skills/applescript.md) — skill · 311 installs
- [claude-for-safari](https://affpapa.org/en/nevibecode/skills/claude-for-safari.md) — skill · 1500 installs
- [capture-screen](https://affpapa.org/en/nevibecode/skills/capture-screen.md) — skill · 1000 installs
- [apple-calendar](https://affpapa.org/en/nevibecode/skills/apple-calendar.md) — skill · 726 installs
- [iCloud MCP](https://affpapa.org/en/nevibecode/mcp/icloud-mcp.md) — MCP server · ★ 69
- [mcp-apple-notes](https://affpapa.org/en/nevibecode/mcp/mcp-apple-notes.md) — MCP server · ★ 53

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md