Altic

Features

90+ tools for macOS automation:

• 📱 Messages & Contacts - Send/read iMessages, list chats, send file attachments, search/get/create/update contacts
• 📝 Notes & Reminders - Create, list, search, update, show, move, complete, and delete notes/reminders
• 📅 Calendar - Create, list, search, update, delete, check availability, and create recurring events
• 🗂️ Files & Finder - Find, inspect, copy, move, rename, reveal, and trash files safely; streaming paginated search sessions
• 📋 Clipboard - Read/write text, copy file paths for Finder paste, and save/set clipboard images
• 🪟 Window & Workspace - List/focus apps and windows, move/resize/center/tile windows, minimize windows, hide apps, and quit apps
• 🌐 Safari - Control tabs, navigate, execute JavaScript
• 🌍 Chrome (CDP) - Open sessions, navigate, click/type, extract data, screenshots
• 📸 Screen Capture - Capture the active display and share image output with the model
• 🖥️ System - Open apps, adjust brightness/volume, visual effects
• ⚙️ Configuration - Get/set runtime config (timeouts, limits, allowed directories) without restarting
• 📊 Audit & Observability - Automatic tool-call logging with rotation and recent-call history
• 🔒 Path Security - Optional allowed-directories allowlist with symlink traversal prevention
• 📎 Resources & Prompts - MCP resources for frontmost app, Finder selection, clipboard; prompts for calendar summaries, iMessage replies, note search

Available Skills

This repo currently includes one shareable skill:

• altic-studio (skills/altic-studio/)
  • Runs local AppleScript automations via osascript through the Bash tool
  • Covers Messages, Contacts, Notes, Reminders, Calendar, Safari, window management, system controls, screenshots, and Chrome CDP browser control
  • Main skill manifest: skills/altic-studio/SKILL.md

Skill Setup (Any Agent)

Install altic-studio directly from this repo with the Skills CLI:

# Preview available skills in this repo
npx skills add altic-dev/altic-mcp --list

# Install skill with interactive mode 
npx skills add altic-dev/altic-mcp 

Restart your coding agent after installation.

Requirements

• macOS 10.13+
• UV package manager (auto-installed by the bash installer if missing)

Python note: altic-mcp requires Python 3.13+ internally, but uvx manages this automatically — you do not need to install Python yourself when using the uvx or bash installer options below.

Security & Runtime Configuration

Allowed Directories (Path Allowlist)

By default, altic-mcp has full filesystem access for file operations. To restrict file tools to specific directories, set the ALLOWED_DIRECTORIES environment variable (colon-separated) or use the set_config_value tool:

# Via environment variable
export ALLOWED_DIRECTORIES="/Users/you/Documents:/Users/you/Desktop"

// Or via the set_config_value MCP tool
{"key": "allowed_directories", "value": ["/Users/you/Documents", "/Users/you/Desktop"]}

All file paths are resolved with symlink traversal prevention — a symlink inside an allowed directory that points outside will be rejected.

Runtime Config

altic-mcp stores runtime configuration at ~/.config/altic-mcp/config.json. Use the get_config and set_config_value MCP tools to inspect and change settings without restarting:

Key	Default	Description
osascript_timeout_seconds	60	Timeout for AppleScript manager calls
file_search_max_results	25	Max results for find_files
clipboard_max_chars	20000	Max chars for clipboard text reads
include_hidden_default	false	Include hidden files in searches by default
allowed_directories	[]	Allowed path roots (empty = full FS)
audit_log_enabled	false	Log tool calls to audit file when enabled
search_visit_limit	50000	Max entries to walk per search batch

Audit Logging

When audit logging is enabled, every tool call is logged to ~/.cache/altic-mcp/audit.jsonl (rotated at 10 MB). Use the get_recent_tool_calls tool to retrieve recent call history with timing and success status.

How to Install

Install in Claude Desktop

altic-mcp offers multiple installation methods for Claude Desktop.

📋 Update & Uninstall Information: Options 1 and 2 have automatic updates. See Updating & Uninstalling below for details.

Option 1: Add to claude_desktop_config manually ⭐ Auto-Updates (Requires UV)

Add this entry to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "altic-mcp": {
      "command": "uvx",
      "args": ["--refresh", "--from", "git+https://github.com/altic-dev/altic-mcp.git", "altic-mcp"]
    }
  }
}

Restart Claude if running.

✅ Auto-Updates: Yes — uvx --refresh re-fetches the latest version from GitHub each time Claude starts 🔄 Manual Update: uv cache clean altic-mcp then restart Claude 🗑️ Uninstall: Remove the "altic-mcp" entry from your claude_desktop_config.json

Performance tip: --refresh ensures you always run the latest version but adds a few seconds to startup. Remove --refresh for faster startup (update manually with uv cache clean altic-mcp).

Option 2: Using bash script installer ⭐ Auto-Updates (Installs UV if needed)

curl -fsSL https://raw.githubusercontent.com/altic-dev/altic-mcp/refs/heads/main/install.sh | bash

This script checks for UV (installs it if missing), backs up your existing Claude config, and adds the altic-mcp server entry automatically.

✅ Auto-Updates: Yes — same uvx --refresh mechanism as Option 1 🔄 Manual Update: Re-run the bash installer command above, or uv cache clean altic-mcp 🗑️ Uninstall: Remove the "altic-mcp" entry from your claude_desktop_config.json

Install in Other Clients

altic-mcp works with any MCP-compatible client. The standard JSON configuration is:

{
  "mcpServers": {
    "altic-mcp": {
      "command": "uvx",
      "args": ["--refresh", "--from", "git+https://github.com/altic-dev/altic-mcp.git", "altic-mcp"]
    }
  }
}

Add this to your client's MCP configuration file at the locations below:

Cursor

Install MCP Server

Or add manually to ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project folder (project-specific).

See Cursor MCP docs for more info.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json. See Windsurf MCP docs for more info.

VS Code / GitHub Copilot

Add to .vscode/mcp.json in your project or VS Code User Settings (JSON). Make sure MCP is enabled under Chat > MCP. Works in Agent mode.

See VS Code MCP docs for more info.

Cline

Configure through the Cline extension settings in VS Code. Open the Cline sidebar, click the MCP Servers icon, and add the JSON configuration above. See Cline MCP docs for more info.

Roo Code

Add to your Roo Code MCP configuration file. See Roo Code MCP docs for more info.

Claude Code

claude mcp add --scope user altic-mcp -- uvx --refresh --from git+https://github.com/altic-dev/altic-mcp.git altic-mcp

Remove --scope user to install for the current project only. See Claude Code MCP docs for more info.

Trae

Use the "Add manually" feature and paste the JSON configuration above. See Trae MCP docs for more info.

Kiro

Navigate to Kiro > MCP Servers, click + Add, and paste the JSON configuration above. See Kiro MCP docs for more info.

Codex (OpenAI)

Codex uses TOML configuration. Run this command to add altic-mcp:

codex mcp add altic-mcp -- uvx --refresh --from git+https://github.com/altic-dev/altic-mcp.git altic-mcp

Or manually add to ~/.codex/config.toml:

[mcp_servers.altic-mcp]
command = "uvx"
args = ["--refresh", "--from", "git+https://github.com/altic-dev/altic-mcp.git", "altic-mcp"]

See Codex MCP docs for more info.

JetBrains (AI Assistant)

In JetBrains IDEs, go to Settings → Tools → AI Assistant → Model Context Protocol (MCP), click + Add, select As JSON, and paste the JSON configuration above. See JetBrains MCP docs for more info.

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "altic-mcp": {
      "command": "uvx",
      "args": ["--refresh", "--from", "git+https://github.com/altic-dev/altic-mcp.git", "altic-mcp"]
    }
  }
}

See Gemini CLI docs for more info.

OpenCode

Add to your opencode.json (project-level) or ~/.config/opencode/opencode.json (global):

{
  "mcp": {
    "altic-mcp": {
      "type": "local",
      "command": ["uvx", "--refresh", "--from", "git+https://github.com/altic-dev/altic-mcp.git", "altic-mcp"],
      "enabled": true
    }
  }
}

See OpenCode MCP docs for more info.

Updating & Uninstalling Altic MCP

Automatic Updates (Options 1 & 2)

Both the manual config (Option 1) and bash installer (Option 2) use uvx --refresh, which automatically re-fetches the latest version from GitHub whenever you restart Claude. No manual intervention needed.

Manual Updates

If you removed --refresh for faster startup, force an update with:

uv cache clean altic-mcp

Then restart Claude Desktop.

Uninstalling Altic MCP

Manual Uninstallation

1. Locate your Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Edit the config file:

   • Open the file in a text editor
   • Find and remove the "altic-mcp" entry from the "mcpServers" section
   • Save the file

Example — remove this section:

"altic-mcp": {
  "command": "uvx",
  "args": ["--refresh", "--from", "git+https://github.com/altic-dev/altic-mcp.git", "altic-mcp"]
}

Close and restart Claude Desktop to complete the removal.

Troubleshooting

If Claude won't start after editing the config:

• Check that your JSON is valid (no trailing commas, matched braces)
• Restore from the backup created by the bash installer (.bak.* file next to your config)
• Re-run the bash installer to regenerate a valid config

Local Development

For contributors who want to run altic-mcp from a local checkout:

# Install UV if needed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and setup
git clone https://github.com/altic-dev/altic-mcp.git
cd altic-mcp
uv sync

# Run the server directly
uv run server.py

# Or build and run via the installed entry point
uv build
uvx --from dist/altic_mcp-0.1.0-py3-none-any.whl altic-mcp

❌ Auto-Updates: No — requires manual git pull to update 🔄 Manual Update: cd altic-mcp && git pull && uv sync 🗑️ Uninstall: Remove the cloned directory and the MCP server entry from your client config

Permissions Required

System Preferences → Privacy & Security:

• ✅ Contacts - For search_contacts
• ✅ Calendars - For calendar events
• ✅ Reminders - For creating reminders
• ✅ Automation - Allow Claude to control apps (Messages, Notes, Safari)
• ✅ Finder Automation - For Finder selection, reveal, and Trash file tools
• ✅ Accessibility - Required for screen glow, system controls, and window management tools such as focus_window, move_window, resize_window, center_window, tile_windows, minimize, hide_app, and quit_app
• ✅ Screen Recording - Required for screenshot capture tools and improves window title/id discovery for list_windows on recent macOS versions

Clipboard text operations normally do not require extra permissions. Clipboard file and image operations use macOS pasteboard APIs and may prompt for security approval depending on the host app and OS settings.

Safari Settings:

Safari → Develop → Allow JavaScript from Apple Events ✅ (Required for Safari tools)

Note: If "Develop" menu is not visible, enable it in Safari → Settings → Advanced → Show Develop menu

Chrome Setup (for CDP tools):

• Install Google Chrome
• The MCP server can auto-start Chrome with --remote-debugging-port when opening a CDP session
• If auto-start fails, launch manually:

open -a "Google Chrome" --args --remote-debugging-port=9222

macOS will prompt for permissions when first used. Grant them to enable full functionality.