launchd-mcp

Manage macOS launchd jobs from MCP tools.

This project provides:

• An MCP server (main.py) that wraps launchctl
• Task management tools for Python-script jobs (link.igtm.launchd-mcp.*)
• Per-task log management and retrieval
• A reusable Agent Skill at skills/launchctl/SKILL.md for users who prefer raw CLI workflows (no MCP server implementation)

Features

• Basic launchctl operations: list, print, kickstart, bootstrap, bootout, enable, disable
• Managed task lifecycle:
  • create_or_update_python_task
  • list_python_tasks
  • get_python_task_logs
  • remove_python_task
• Scheduling and event options:
  • StartInterval (seconds)
  • StartCalendarInterval
  • WatchPaths
  • QueueDirectories
• Runtime tuning options:
  • KeepAlive, ThrottleInterval, ProcessType, Nice, Umask, HardResourceLimits

Requirements

• macOS (Darwin) for launchctl execution
• Python 3.13+
• uv

Install

git clone git@github.com:igtm/launchd-mcp.git
cd launchd-mcp
uv sync

Run MCP Server

uv run main.py

Claude Desktop Example

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "launchd": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/launchd-mcp",
        "run",
        "main.py"
      ]
    }
  }
}

Logs

Managed task logs are written to:

• ~/.local/share/launchd-mcp/logs/{label}.out.log
• ~/.local/share/launchd-mcp/logs/{label}.err.log

Tests

uv run pytest

Agent Skill (CLI-first)

If you prefer managing launchd directly with shell/launchctl/plist files (without MCP server implementation), use:

• skills/launchctl/SKILL.md

This Skill follows the same label, task, and log conventions as this repository.

Safety Notes

• For stdio MCP servers, never print to stdout except protocol messages.
• Treat python_script input as untrusted unless validated.
• Validate generated plist files (plutil -lint) before launchctl bootstrap.