# Altic MCP

Altic MCP turns Claude into a hands-on Mac operator. Connect 64 precise tools for Messages, Contacts, Notes, Reminders, Calendar, Files, Finder, Clipboard, Window & Workspace, Safari, Chrome CDP, screen capture, system controls, and visual feedback, all through an open source Model Context Protocol server for macOS.

Canonical URL: https://altic.dev/mcp
Markdown URL: https://altic.dev/mcp.md
Tool inventory JSON: https://altic.dev/mcp/tools.json
Repository: https://github.com/altic-dev/altic-mcp
Server source: https://github.com/altic-dev/altic-mcp/blob/main/server.py

## Quick Facts

- Category: Model Context Protocol server and macOS automation tool
- License: Apache-2.0
- README tool claim: 40+ tools
- Exact server.py tool count: 64
- Skill: altic-studio
- Requirements: macOS 10.13+; Python 3.13+; UV package manager; Google Chrome for Chrome CDP tools

## Requirements

- macOS 10.13+
- Python 3.13+
- UV package manager
- Google Chrome for Chrome CDP tools

## Setup

1. Install UV if needed

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

2. Clone and set up the repository

```bash
git clone https://github.com/altic-dev/altic-mcp.git && cd altic-mcp && uv sync
```

3. Test locally

```bash
uv run server.py
```

4. Configure Claude Desktop

```bash
uv run --project /FULL/PATH/TO/altic-mcp /FULL/PATH/TO/altic-mcp/server.py
```

## Skill Installation

```bash
npx skills add altic-dev/altic-mcp --list
```

```bash
npx skills add altic-dev/altic-mcp
```

## Required Permissions

- Contacts for search_contacts
- Calendars for calendar events
- Reminders for creating reminders
- Automation so Claude can control apps such as Messages, Notes, Safari, and Finder
- Finder Automation for Finder selection, reveal, and Trash file tools
- Accessibility for screen glow, system controls, and window management tools
- Screen Recording for screenshot capture tools and improved list_windows discovery on recent macOS versions
- Clipboard text operations usually need no extra permission; clipboard file and image operations may prompt depending on host app and OS settings
- Safari -> Develop -> Allow JavaScript from Apple Events for Safari tools
- Google Chrome for Chrome CDP tools

## Tool Categories

### Messages & Contacts (3 tools)

Send and read iMessages, search contacts, and resolve phone numbers.

- `search_contacts`
- `send_imessage`
- `read_recent_messages`

### Notes & Reminders (3 tools)

Create and search Apple Notes, then create time-based reminders.

- `create_note`
- `search_notes`
- `set_reminder`

### Calendar (2 tools)

Create Calendar events and list events for a specific day.

- `create_calendar_event`
- `list_calendar_events_for_day`

### Files & Finder (10 tools)

Find, inspect, copy, move, rename, reveal, and trash files safely, with dry-run support for destructive-looking actions.

- `find_files`
- `list_directory`
- `get_file_info`
- `copy_file`
- `copy_directory`
- `move_file`
- `rename_file`
- `trash_file`
- `reveal_in_finder`
- `get_finder_selection`

### Clipboard (7 tools)

Read, write, clear, save, and set macOS clipboard text, files, and images.

- `get_clipboard_text`
- `set_clipboard_text`
- `clear_clipboard`
- `get_clipboard_files`
- `set_clipboard_files`
- `save_clipboard_image`
- `set_clipboard_image`

### Window & Workspace (10 tools)

Inspect, focus, move, resize, center, tile, minimize, hide, and quit macOS app windows.

- `get_frontmost_app`
- `list_windows`
- `focus_window`
- `move_window`
- `resize_window`
- `center_window`
- `tile_windows`
- `minimize`
- `hide_app`
- `quit_app`

### Safari (12 tools)

Control Safari tabs, windows, navigation, history, JavaScript, and page inspection.

- `open_safari_tab`
- `close_safari_tab`
- `get_safari_tabs`
- `switch_safari_tab`
- `run_safari_javascript`
- `navigate_safari`
- `reload_safari_page`
- `safari_go_back`
- `safari_go_forward`
- `open_safari_window`
- `close_safari_window`
- `get_safari_page_info`

### Chrome CDP (9 tools)

Use session-based Chrome DevTools Protocol control for navigate, wait, click, type, extract, screenshot, and close workflows.

- `chrome_open_session`
- `chrome_list_sessions`
- `chrome_navigate`
- `chrome_wait_for`
- `chrome_click`
- `chrome_type`
- `chrome_extract`
- `chrome_screenshot`
- `chrome_close_session`

### Screen Capture (1 tools)

Capture the active display and return image output directly to the model.

- `capture_active_screen`

### System (5 tools)

Open apps and adjust brightness or system volume.

- `open_app`
- `decrease_brightness`
- `increase_brightness`
- `turn_up_volume`
- `turn_down_volume`

### Visual Feedback (2 tools)

Add and remove a screen glow so the user can see when automation is active.

- `add_screen_glow`
- `remove_screen_glow`

## Exact Tool Inventory

### open_app

Category: System

Open any macOS application by name.

Arguments:
- `name` (string, required): Name of the Mac app, such as Mail, Contacts, or Messages.

Permissions: Automation

### get_frontmost_app

Category: Window & Workspace

Get the currently frontmost macOS application.

Arguments:
No arguments.

Permissions: Accessibility

### list_windows

Category: Window & Workspace

List manageable macOS windows with app metadata, frames, and display indexes.

Arguments:
- `app_name` (string, optional): Optional app name, bundle id, or process name filter.
- `include_minimized` (boolean, optional, default false): Include minimized windows when available.

Permissions: Accessibility, Screen Recording

### focus_window

Category: Window & Workspace

Focus a macOS window by window id, app name, or frontmost fallback.

Arguments:
- `app_name` (string, optional): Optional app name, bundle id, or process name.
- `window_id` (integer | null, optional, default null): Optional CoreGraphics window id.
- `window_index` (integer | null, optional, default null): Optional 1-based index among the app's windows.

Permissions: Accessibility

### move_window

Category: Window & Workspace

Move a macOS window to a display-aware top-left position.

Arguments:
- `x` (integer, required): Target top-left x coordinate.
- `y` (integer, required): Target top-left y coordinate.
- `app_name` (string, optional): Optional app name, bundle id, or process name.
- `window_id` (integer | null, optional, default null): Optional CoreGraphics window id.
- `window_index` (integer | null, optional, default null): Optional 1-based index among the app's windows.
- `display_index` (integer | null, optional, default null): Optional 1-based display index for clamping placement.

Permissions: Accessibility

### resize_window

Category: Window & Workspace

Resize a macOS window and clamp it to the selected or current display.

Arguments:
- `width` (integer, required): Target width in points.
- `height` (integer, required): Target height in points.
- `app_name` (string, optional): Optional app name, bundle id, or process name.
- `window_id` (integer | null, optional, default null): Optional CoreGraphics window id.
- `window_index` (integer | null, optional, default null): Optional 1-based index among the app's windows.
- `display_index` (integer | null, optional, default null): Optional 1-based display index for clamping placement.

Permissions: Accessibility

### center_window

Category: Window & Workspace

Center a macOS window on its current display or a selected display.

Arguments:
- `app_name` (string, optional): Optional app name, bundle id, or process name.
- `window_id` (integer | null, optional, default null): Optional CoreGraphics window id.
- `window_index` (integer | null, optional, default null): Optional 1-based index among the app's windows.
- `display_index` (integer | null, optional, default null): Optional 1-based display index.
- `width` (integer | null, optional, default null): Optional width to apply before centering.
- `height` (integer | null, optional, default null): Optional height to apply before centering.

Permissions: Accessibility

### tile_windows

Category: Window & Workspace

Tile multiple macOS windows on a display.

Arguments:
- `layout` (string, optional, default columns): Tile layout: columns, rows, or grid.
- `app_names` (string[] | null, optional, default null): Optional app names to tile in order; defaults to visible windows.
- `display_index` (integer | null, optional, default null): Optional 1-based display index.
- `padding` (integer, optional, default 8): Gap around and between windows.

Permissions: Accessibility

### minimize

Category: Window & Workspace

Minimize a macOS window.

Arguments:
- `app_name` (string, optional): Optional app name, bundle id, or process name.
- `window_id` (integer | null, optional, default null): Optional CoreGraphics window id.
- `window_index` (integer | null, optional, default null): Optional 1-based index among the app's windows.

Permissions: Accessibility

### hide_app

Category: Window & Workspace

Hide a running macOS app.

Arguments:
- `app_name` (string, required): App name, bundle id, or process name.

Permissions: Accessibility

### quit_app

Category: Window & Workspace

Quit a running macOS app.

Arguments:
- `app_name` (string, required): App name, bundle id, or process name.

Permissions: Accessibility

### find_files

Category: Files & Finder

Find files by name using Spotlight first, with Python filesystem fallback.

Arguments:
- `query` (string, required): File name or Spotlight query text.
- `root` (string, optional): Optional directory to search within.
- `max_results` (integer, optional, default 25): Maximum results, 1 to 500.
- `include_hidden` (boolean, optional, default false): Include hidden files and folders.
- `kind` (string, optional, default auto): Search backend: auto, name, or spotlight.

Permissions: Finder Automation

### list_directory

Category: Files & Finder

List immediate children of a directory with metadata.

Arguments:
- `path` (string, required): Directory path to list.
- `include_hidden` (boolean, optional, default false): Include hidden files and folders.
- `max_results` (integer, optional, default 200): Maximum children to return, 1 to 1000.

Permissions: Filesystem

### get_file_info

Category: Files & Finder

Get metadata for a file, directory, or missing path.

Arguments:
- `path` (string, required): File or directory path.

Permissions: Filesystem

### copy_file

Category: Files & Finder

Copy a file with metadata. Directories require copy_directory.

Arguments:
- `source` (string, required): Existing source file path.
- `destination` (string, required): Destination file path.
- `overwrite` (boolean, optional, default false): Allow replacing an existing destination.
- `dry_run` (boolean, optional, default false): Return the planned action without copying.

Permissions: Filesystem

### copy_directory

Category: Files & Finder

Copy a directory tree. Existing destinations fail unless overwrite is true.

Arguments:
- `source` (string, required): Existing source directory path.
- `destination` (string, required): Destination directory path.
- `overwrite` (boolean, optional, default false): Allow merging into an existing destination.
- `dry_run` (boolean, optional, default false): Return the planned action without copying.

Permissions: Filesystem

### move_file

Category: Files & Finder

Move a file or directory. Existing destinations fail unless overwrite is true.

Arguments:
- `source` (string, required): Existing source path.
- `destination` (string, required): Destination path.
- `overwrite` (boolean, optional, default false): Allow replacing an existing destination.
- `dry_run` (boolean, optional, default false): Return the planned action without moving.

Permissions: Filesystem

### rename_file

Category: Files & Finder

Rename a file or directory within its current parent directory.

Arguments:
- `path` (string, required): Existing file or directory path.
- `new_name` (string, required): New file name only, not a path.
- `overwrite` (boolean, optional, default false): Allow replacing an existing destination.
- `dry_run` (boolean, optional, default false): Return the planned action without renaming.

Permissions: Filesystem

### trash_file

Category: Files & Finder

Move a file or directory to the macOS Trash. Permanent delete is not supported.

Arguments:
- `path` (string, required): Existing file or directory path.
- `dry_run` (boolean, optional, default false): Return the planned action without moving to Trash.

Permissions: Finder Automation

### reveal_in_finder

Category: Files & Finder

Reveal a file or directory in Finder.

Arguments:
- `path` (string, required): Existing file or directory path.

Permissions: Finder Automation

### get_finder_selection

Category: Files & Finder

Get currently selected Finder items as paths and metadata.

Arguments:
No arguments.

Permissions: Finder Automation

### get_clipboard_text

Category: Clipboard

Read plain text from the macOS clipboard.

Arguments:
- `max_chars` (integer, optional, default 20000): Maximum number of characters to return.

Permissions: Clipboard

### set_clipboard_text

Category: Clipboard

Write plain text to the macOS clipboard.

Arguments:
- `text` (string, required): Text to place on the clipboard.

Permissions: Clipboard

### clear_clipboard

Category: Clipboard

Clear clipboard contents.

Arguments:
No arguments.

Permissions: Clipboard

### get_clipboard_files

Category: Clipboard

Return file URLs currently available on the macOS clipboard.

Arguments:
No arguments.

Permissions: Clipboard

### set_clipboard_files

Category: Clipboard

Put one or more filesystem paths on the macOS clipboard for Finder paste.

Arguments:
- `paths` (string[], required): Existing file or directory paths to place on the clipboard.

Permissions: Clipboard

### save_clipboard_image

Category: Clipboard

Save an image from the macOS clipboard to a PNG file and share it with the model.

Arguments:
- `output_path` (string, optional): Optional output path for the PNG.

Permissions: Clipboard

### set_clipboard_image

Category: Clipboard

Put an image file on the macOS clipboard.

Arguments:
- `path` (string, required): Existing image file path.

Permissions: Clipboard

### send_imessage

Category: Messages & Contacts

Send an iMessage to a phone number.

Arguments:
- `phone_number` (string, required): Recipient phone number.
- `message` (string, required): Message text to send.

Permissions: Contacts, Automation

### search_contacts

Category: Messages & Contacts

Search Contacts by name and return matching people and phone numbers.

Arguments:
- `name` (string, required): Contact name to search for.

Permissions: Contacts

### read_recent_messages

Category: Messages & Contacts

Read recent iMessages between the user and a phone number.

Arguments:
- `phone_number` (string, required): Phone number for the conversation.
- `recent_message_count` (integer, optional, default 25): Number of recent messages to retrieve, 1 to 200.

Permissions: Automation

### set_reminder

Category: Notes & Reminders

Create a macOS reminder with a specific date, time, and list.

Arguments:
- `name` (string, required): Reminder text.
- `datetime` (string, required): Time in YYYY-MM-DD HH:MM format.
- `list_name` (string, optional, default Reminders): Reminder list name.

Permissions: Reminders

### create_note

Category: Notes & Reminders

Create a note in Apple Notes.

Arguments:
- `name` (string, required): Note title.
- `body` (string, required): Note body.
- `folder` (string, optional): Optional folder. Uses default folder if omitted.

Permissions: Automation

### search_notes

Category: Notes & Reminders

Search Apple Notes.

Arguments:
- `query` (string, required): Search query.
- `max_results` (integer, optional, default 10): Maximum results, 1 to 20.

Permissions: Automation

### decrease_brightness

Category: System

Decrease screen brightness.

Arguments:
- `amount` (number, optional, default 0.0625): Brightness decrement on a 0.0 to 1.0 scale.

Permissions: Accessibility

### increase_brightness

Category: System

Increase screen brightness.

Arguments:
- `amount` (number, optional, default 0.0625): Brightness increment on a 0.0 to 1.0 scale.

Permissions: Accessibility

### turn_up_volume

Category: System

Turn up system volume.

Arguments:
- `amount` (number, optional, default 6.25): Volume increase on a 0 to 100 scale.

Permissions: Accessibility

### turn_down_volume

Category: System

Turn down system volume.

Arguments:
- `amount` (number, optional, default 6.25): Volume decrease on a 0 to 100 scale.

Permissions: Accessibility

### create_calendar_event

Category: Calendar

Create an event in macOS Calendar.

Arguments:
- `title` (string, required): Event title.
- `start_datetime` (string, required): Start date and time in YYYY-MM-DD HH:MM format.
- `duration_minutes` (integer, required): Duration in minutes.
- `calendar_name` (string, optional): Optional calendar name. Uses default calendar if omitted.

Permissions: Calendars

### list_calendar_events_for_day

Category: Calendar

List Calendar events for a specific day.

Arguments:
- `date` (string, required): Date in YYYY-MM-DD format.

Permissions: Calendars

### open_safari_tab

Category: Safari

Open a new Safari tab with an optional URL.

Arguments:
- `url` (string, optional): Optional URL to open.

Permissions: Automation, Safari JavaScript from Apple Events

### close_safari_tab

Category: Safari

Close a Safari tab.

Arguments:
- `tab_index` (integer, optional, default -1): Use -1 for current tab or a 1-based tab index.

Permissions: Automation

### get_safari_tabs

Category: Safari

List all open Safari tabs with URLs and titles.

Arguments:
No arguments.

Permissions: Automation

### switch_safari_tab

Category: Safari

Switch to a Safari tab by 1-based index.

Arguments:
- `tab_index` (integer, required): 1-based tab index.

Permissions: Automation

### run_safari_javascript

Category: Safari

Execute JavaScript in the current Safari tab.

Arguments:
- `javascript_code` (string, required): JavaScript code to execute.

Permissions: Automation, Safari JavaScript from Apple Events

### navigate_safari

Category: Safari

Navigate the current Safari tab to a URL.

Arguments:
- `url` (string, required): Destination URL.

Permissions: Automation

### reload_safari_page

Category: Safari

Reload the current Safari page.

Arguments:
No arguments.

Permissions: Automation

### safari_go_back

Category: Safari

Navigate back in Safari history.

Arguments:
No arguments.

Permissions: Automation

### safari_go_forward

Category: Safari

Navigate forward in Safari history.

Arguments:
No arguments.

Permissions: Automation

### open_safari_window

Category: Safari

Open a new Safari window with an optional URL.

Arguments:
- `url` (string, optional): Optional URL to open.

Permissions: Automation

### close_safari_window

Category: Safari

Close the current Safari window.

Arguments:
No arguments.

Permissions: Automation

### get_safari_page_info

Category: Safari

Get current Safari page URL, title, text content, and HTML source.

Arguments:
No arguments.

Permissions: Automation, Safari JavaScript from Apple Events

### chrome_open_session

Category: Chrome CDP

Open a Chrome automation session for browser control.

Arguments:
- `start_url` (string, optional, default about:blank): Initial page URL.
- `debug_port` (integer, optional, default 9222): Chrome remote debugging port, 1024 to 65535.
- `headless` (boolean, optional, default false): Launch Chrome headless if debugger needs to be started.

Permissions: Google Chrome

### chrome_list_sessions

Category: Chrome CDP

List active Chrome automation sessions.

Arguments:
No arguments.

Permissions: Google Chrome

### chrome_navigate

Category: Chrome CDP

Navigate an active Chrome CDP session to a URL.

Arguments:
- `session_id` (string, required): Session returned by chrome_open_session.
- `url` (string, required): URL to load.

Permissions: Google Chrome

### chrome_wait_for

Category: Chrome CDP

Wait for a CSS selector in a Chrome CDP session.

Arguments:
- `session_id` (string, required): Session returned by chrome_open_session.
- `selector` (string, required): CSS selector to wait for.
- `timeout_ms` (integer, optional, default 10000): Maximum wait time in milliseconds.
- `poll_ms` (integer, optional, default 200): Polling interval in milliseconds.

Permissions: Google Chrome

### chrome_click

Category: Chrome CDP

Click an element in an active Chrome CDP session.

Arguments:
- `session_id` (string, required): Session returned by chrome_open_session.
- `selector` (string, required): CSS selector for target element.

Permissions: Google Chrome

### chrome_type

Category: Chrome CDP

Type text into an input element in an active Chrome CDP session.

Arguments:
- `session_id` (string, required): Session returned by chrome_open_session.
- `selector` (string, required): CSS selector for target input.
- `text` (string, required): Text to type.
- `clear_first` (boolean, optional, default true): Clear existing value before typing.

Permissions: Google Chrome

### chrome_extract

Category: Chrome CDP

Extract data by selector, attribute, or JavaScript expression.

Arguments:
- `session_id` (string, required): Session returned by chrome_open_session.
- `selector` (string, optional): CSS selector to query.
- `attribute` (string, optional): Attribute name to read from selected element.
- `javascript_expression` (string, optional): JavaScript expression to evaluate.

Permissions: Google Chrome

### chrome_screenshot

Category: Chrome CDP

Capture a screenshot of an active Chrome CDP session.

Arguments:
- `session_id` (string, required): Session returned by chrome_open_session.
- `output_path` (string, optional): Optional output PNG path.

Permissions: Google Chrome

### chrome_close_session

Category: Chrome CDP

Close a Chrome automation session.

Arguments:
- `session_id` (string, required): Session returned by chrome_open_session.

Permissions: Google Chrome

### capture_active_screen

Category: Screen Capture

Capture a full screenshot of the display containing the frontmost app and return image output to the model.

Arguments:
- `output_path` (string, optional): Optional output PNG path.

Permissions: Screen Recording

### add_screen_glow

Category: Visual Feedback

Add an orange screen-edge glow to show that automation is in progress.

Arguments:
No arguments.

Permissions: Accessibility

### remove_screen_glow

Category: Visual Feedback

Remove the screen glow when automation completes.

Arguments:
No arguments.

Permissions: Accessibility

## Example Workflows

- Prompt: Find Sam in contacts and send an iMessage: Running 10 mins late.
  Tool path: search_contacts -> send_imessage
- Prompt: Create tomorrow 9:30 AM standup in Work calendar for 30 minutes.
  Tool path: create_calendar_event
- Prompt: Find the project brief, inspect metadata, copy it to a review folder, and reveal it in Finder.
  Tool path: find_files -> get_file_info -> copy_file -> reveal_in_finder
- Prompt: Open a Chrome session, navigate to GitHub, wait for a selector, and extract page text.
  Tool path: chrome_open_session -> chrome_navigate -> chrome_wait_for -> chrome_extract
- Prompt: Capture my active display and attach the screenshot for review.
  Tool path: capture_active_screen
- Prompt: Read my clipboard text, summarize it, then replace it with the cleaned version.
  Tool path: get_clipboard_text -> set_clipboard_text
- Prompt: Tile Safari and Notes side by side on my current display.
  Tool path: list_windows -> tile_windows

## FAQ

### What is Altic MCP?

Altic MCP is an open source Model Context Protocol server that lets MCP clients automate macOS apps and browser sessions.

### How many tools does Altic MCP expose?

The README describes 40+ tools. The current server.py source exposes 64 exact MCP tools.

### Which automation areas are covered?

Altic MCP covers Messages and Contacts, Notes and Reminders, Calendar, Files and Finder, Clipboard, Window and Workspace, Safari, Chrome CDP, Screen Capture, System controls, and Visual Feedback.

### What is altic-studio?

altic-studio is the shareable skill in the Altic MCP repo. It runs AppleScript automations via osascript and supports Messages, Contacts, Notes, Reminders, Calendar, Files and Finder workflows, Clipboard operations, Window and Workspace management, Safari, system controls, screenshots, and Chrome CDP browser control.

### What are the requirements?

Altic MCP requires macOS 10.13+, Python 3.13+, the UV package manager, and Google Chrome for Chrome CDP tools.

### What permissions are required?

Contacts, Calendars, Reminders, Automation, Finder Automation, Accessibility, and Screen Recording are required for the corresponding macOS integrations. Clipboard file and image operations may prompt depending on host app and OS settings. Safari tools also require Safari's Allow JavaScript from Apple Events setting.