# Altic MCP

## 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:

```bash
# 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](https://docs.astral.sh/uv/getting-started/installation/) (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:

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

```json
// 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](#updating--uninstalling-altic-mcp) 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):

```json
{
  "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)**

```bash
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:

```json
{
  "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](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=altic-mcp&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLXJlZnJlc2giLCItLWZyb20iLCJnaXQraHR0cHM6Ly9naXRodWIuY29tL2FsdGljLWRldi9hbHRpYy1tY3AuZ2l0IiwiYWx0aWMtbWNwIl19)

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

See [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.

**Windsurf**

Add to `~/.codeium/windsurf/mcp_config.json`. See [Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp) 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](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) 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](https://docs.cline.bot/mcp/configuring-mcp-servers) for more info.

**Roo Code**

Add to your Roo Code MCP configuration file. See [Roo Code MCP docs](https://docs.roocode.com/features/mcp/using-mcp-in-roo) for more info.

**Claude Code**

```bash
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](https://docs.anthropic.com/en/docs/claude-code/mcp) for more info.

**Trae**

Use the "Add manually" feature and paste the JSON configuration above. See [Trae MCP docs](https://docs.trae.ai/ide/model-context-protocol?_lang=en) for more info.

**Kiro**

Navigate to `Kiro` > `MCP Servers`, click `+ Add`, and paste the JSON configuration above. See [Kiro MCP docs](https://kiro.dev/docs/mcp/configuration/) for more info.

**Codex (OpenAI)**

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

```bash
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`:

```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](https://developers.openai.com/codex/mcp/) 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](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html) for more info.

**Gemini CLI**

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

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

See [Gemini CLI docs](https://github.com/google-gemini/gemini-cli) for more info.

**OpenCode**

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

```json
{
  "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](https://opencode.ai/docs/mcp-servers) 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:

```bash
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:**

```json
"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:

```bash
# 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:

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

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