Meta Agent Tools
PT

Back to the catalog

controlmac

Control macOS via AppleScript - volume, apps, notifications, clipboard, Finder and more

Open source Open in the app JSON README (API)

About

Control macOS via AppleScript - volume, apps, notifications, clipboard, Finder and more

Details

Kind
Plugins
Topic
No topic detected
Publisher
ramgeart
Origin
gemini
Category
ferramentas
Version
1.0.0
Stars
1
Last push
2026-02-02T02:15:31Z
Repository state
ativo
License
MIT
Added
2026-08-30 14:13:39
Updated
2026-08-30 14:13:39
Origin id
ramgeart/controlmac-gemini-extension

README

# ControlMac - Gemini CLI Extension

[![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-Extension-blue)](https://geminicli.com/extensions/)
[![npm](https://img.shields.io/npm/v/controlmac-mcp)](https://www.npmjs.com/package/controlmac-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Control macOS via AppleScript directly from Gemini CLI. This extension provides 27 tools for system control, app management, notifications, clipboard, and Finder operations.

## Installation

### From Extensions Gallery (Recommended)

```bash
gemini extensions install controlmac
```

### Manual Installation

```bash
# Clone the extension
git clone https://github.com/ramgeart/controlmac-gemini-extension.git ~/.gemini/extensions/controlmac

# Or copy to extensions directory
cp -r controlmac-gemini-extension ~/.gemini/extensions/controlmac
```

### Direct MCP Configuration

Add to `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "controlmac": {
      "command": "npx",
      "args": ["-y", "controlmac-mcp"],
      "trust": true
    }
  }
}
```

## Features

| Category | Tools |
|----------|-------|
| **Core** | Execute AppleScript/JXA code |
| **System** | Volume, brightness, dark mode, system info, sleep, trash |
| **Apps** | Open, quit, list, hide, show, get windows |
| **Notifications** | Notifications, dialogs, alerts, text-to-speech |
| **Clipboard** | Get, set, clear |
| **Finder** | Open paths, reveal, selected files, new window, open URLs |

## Usage

Once installed, just ask Gemini naturally:

```
> Set the volume to 30%
> Open Safari
> Show me what apps are running
> Enable dark mode
> Display a notification saying "Hello World"
> What's in my clipboard?
> Open my Downloads folder
```

## Verify Installation

```bash
# Check if the extension is loaded
gemini> /mcp

# See available tools
gemini> /mcp desc controlmac
```

## Requirements

- macOS (uses AppleScript)
- Node.js 18+
- Gemini CLI

## Available Tools

- `macos_osascript` - Execute AppleScript/JXA
- `macos_set_volume` / `macos_get_volume` / `macos_set_mute`
- `macos_set_brightness`
- `macos_get_system_info`
- `macos_sleep_display`
- `macos_empty_trash`
- `macos_set_dark_mode` / `macos_get_dark_mode`
- `macos_open_app` / `macos_quit_app` / `macos_list_apps`
- `macos_get_frontmost_app` / `macos_hide_app` / `macos_show_all_apps`
- `macos_get_app_windows`
- `macos_notification` / `macos_dialog` / `macos_alert` / `macos_speak`
- `macos_get_clipboard` / `macos_set_clipboard` / `macos_clear_clipboard`
- `macos_open_path` / `macos_reveal_in_finder`
- `macos_get_selected_files` / `macos_get_finder_path`
- `macos_new_finder_window` / `macos_open_url`

## Related

- [controlmac-mcp](https://github.com/ramgeart/controlmac-mcp) - The underlying MCP server (also works with Claude Desktop)
- [Gemini CLI Extensions](https://geminicli.com/docs/extensions/)
- [MCP Servers Guide](https://geminicli.com/docs/tools/mcp-server/)

## License

MIT

More