claude-coder-mac-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 pm990320
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# claude-coder-mac-mcp
+
+An MCP server that allows Claude Desktop to spawn new Claude Code instances in iTerm2 windows.
+
+## Features
+
+- **spawn_claude_coder**: Spawn a new Claude Code instance with a given prompt
+  - Opens a new iTerm2 window
+  - Optionally runs with `--dangerously-skip-permissions` (must be enabled on server)
+  - Passes your prompt directly to Claude
+  - The terminal becomes fully interactive
+
+- **list_iterm_windows**: List all iTerm2 windows and sessions
+
+## Requirements
+
+- macOS
+- [iTerm2](https://iterm2.com/) installed
+- [Claude Code CLI](https://claude.ai/code) installed
+- Automation permissions granted to the MCP host app
+
+## Installation
+
+### Via npm (recommended)
+
+```bash
+npm install -g claude-coder-mac-mcp
+```
+
+### From source
+
+```bash
+git clone https://github.com/pm990320/claude-coder-mac-mcp.git
+cd claude-coder-mac-mcp
+npm install
+npm run build
+```
+
+### Verify installation
+
+```bash
+claude-coder-mac-mcp check
+```
+
+This runs environment checks to verify macOS, iTerm2, Claude Code CLI, and automation permissions are all configured correctly.
+
+## CLI Usage
+
+The CLI has multiple commands:
+
+```bash
+# Show help
+claude-coder-mac-mcp --help
+
+# Start the MCP server (used by Claude Desktop)
+# By default, spawned Claude instances run in normal mode (user must approve actions)
+claude-coder-mac-mcp mcp
+
+# Start the MCP server with --dangerously-skip-permissions enabled
+# WARNING: This allows spawned Claude instances to run without user approval
+claude-coder-mac-mcp mcp --dangerously-skip-permissions
+
+# Test spawning a Claude Code instance directly (normal mode)
+claude-coder-mac-mcp spawn "Help me write a REST API"
+claude-coder-mac-mcp spawn "Fix the tests" -d ~/myproject -t "Test Fixer"
+
+# Test spawning with --dangerously-skip-permissions
+claude-coder-mac-mcp spawn "Fix the tests" --dangerously-skip-permissions
+
+# List current iTerm2 windows
+claude-coder-mac-mcp list
+
+# Check environment is configured correctly
+claude-coder-mac-mcp check
+```
+
+## Claude Desktop Configuration
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+**Normal mode** (user must approve Claude Code actions):
+```json
+{
+  "mcpServers": {
+    "claude-coder-mac": {
+      "command": "node",
+      "args": ["/path/to/claude-coder-mac-mcp/dist/index.js", "mcp"]
+    }
+  }
+}
+```
+
+**With --dangerously-skip-permissions** (Claude Code runs autonomously):
+```json
+{
+  "mcpServers": {
+    "claude-coder-mac": {
+      "command": "node",
+      "args": ["/path/to/claude-coder-mac-mcp/dist/index.js", "mcp", "--dangerously-skip-permissions"]
+    }
+  }
+}
+```
+
+## Usage with Claude Desktop
+
+Once configured, you can ask Claude Desktop to spawn new Claude Code instances:
+
+> "Start a new Claude coder to work on my project at ~/myproject with the task: implement user authentication"
+
+Claude will use the `spawn_claude_coder` tool to open iTerm2 with a new Claude Code session.
+
+## Permissions
+
+On first use, macOS will ask you to grant automation permissions. Go to:
+
+**System Settings > Privacy & Security > Automation**
+
+And ensure the app running the MCP server (e.g., Claude Desktop) has permission to control iTerm2.
+
+## MCP Tool Parameters
+
+### spawn_claude_coder
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `prompt` | Yes | The task/prompt to give to Claude Code |
+| `workingDirectory` | No | Directory to run Claude Code in (defaults to ~) |
+| `windowTitle` | No | Custom title for the iTerm2 window |
+
+Note: Whether `--dangerously-skip-permissions` is passed to spawned Claude instances is controlled by the server startup flag, not by tool parameters.
+
+### list_iterm_windows
+
+No parameters. Lists all open iTerm2 windows and their sessions.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Lint
+npm run lint
+
+# Fix lint issues
+npm run fix
+
+# Type check
+npm run typecheck
+```
+
+## Project Structure
+
+```
+src/
+├── index.ts    # CLI entrypoint (uses commander)
+├── server.ts   # MCP server setup and tool registration
+├── spawn.ts    # Core spawn functionality
+├── iterm.ts    # iTerm2 AppleScript utilities
+└── check.ts    # Environment verification checks
+
+tests/
+├── spawn.test.ts   # Unit tests for spawn functions
+└── iterm.test.ts   # Unit tests for iTerm utilities
+```
+
+The modules are separated for testability - `spawn.ts` and `iterm.ts` contain pure functions that can be unit tested independently.
+
+## License
+
+MIT

package/dist/check.d.ts

@@ -0,0 +1,37 @@
+export interface CheckResult {
+    name: string;
+    status: 'pass' | 'fail' | 'warn';
+    message: string;
+}
+export interface EnvironmentCheckResult {
+    allPassed: boolean;
+    checks: CheckResult[];
+}
+/**
+ * Check if running on macOS
+ */
+export declare function checkMacOS(): CheckResult;
+/**
+ * Check if iTerm2 is installed
+ */
+export declare function checkITerm2(): Promise<CheckResult>;
+/**
+ * Check if Claude Code CLI is installed
+ */
+export declare function checkClaudeCode(): Promise<CheckResult>;
+/**
+ * Check if automation permissions are granted for iTerm2
+ */
+export declare function checkAutomationPermissions(): Promise<CheckResult>;
+/**
+ * Check if Node.js version meets requirements
+ */
+export declare function checkNodeVersion(): CheckResult;
+/**
+ * Run all environment checks
+ */
+export declare function runAllChecks(): Promise<EnvironmentCheckResult>;
+/**
+ * Format check results for display
+ */
+export declare function formatCheckResults(result: EnvironmentCheckResult): string;

package/dist/check.js

@@ -0,0 +1,173 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import * as os from 'os';
+const execAsync = promisify(exec);
+/**
+ * Check if running on macOS
+ */
+export function checkMacOS() {
+    const platform = os.platform();
+    if (platform === 'darwin') {
+        const release = os.release();
+        return {
+            name: 'macOS',
+            status: 'pass',
+            message: `Running on macOS (Darwin ${release})`,
+        };
+    }
+    return {
+        name: 'macOS',
+        status: 'fail',
+        message: `This tool requires macOS. Current platform: ${platform}`,
+    };
+}
+/**
+ * Check if iTerm2 is installed
+ */
+export async function checkITerm2() {
+    try {
+        // Check if iTerm2 app exists
+        await execAsync('test -d "/Applications/iTerm.app"');
+        return {
+            name: 'iTerm2',
+            status: 'pass',
+            message: 'iTerm2 is installed at /Applications/iTerm.app',
+        };
+    }
+    catch {
+        return {
+            name: 'iTerm2',
+            status: 'fail',
+            message: 'iTerm2 is not installed. Download from https://iterm2.com/ or install via: brew install --cask iterm2',
+        };
+    }
+}
+/**
+ * Check if Claude Code CLI is installed
+ */
+export async function checkClaudeCode() {
+    try {
+        const { stdout } = await execAsync('which claude');
+        const path = stdout.trim();
+        // Try to get version
+        try {
+            const { stdout: versionOut } = await execAsync('claude --version');
+            const version = versionOut.trim();
+            return {
+                name: 'Claude Code CLI',
+                status: 'pass',
+                message: `Claude Code CLI found at ${path} (${version})`,
+            };
+        }
+        catch {
+            return {
+                name: 'Claude Code CLI',
+                status: 'pass',
+                message: `Claude Code CLI found at ${path}`,
+            };
+        }
+    }
+    catch {
+        return {
+            name: 'Claude Code CLI',
+            status: 'fail',
+            message: 'Claude Code CLI is not installed. Install from https://claude.ai/code',
+        };
+    }
+}
+/**
+ * Check if automation permissions are granted for iTerm2
+ */
+export async function checkAutomationPermissions() {
+    try {
+        // Try a simple AppleScript that requires iTerm2 automation permission
+        await execAsync('osascript -e \'tell application "iTerm2" to get name\'');
+        return {
+            name: 'Automation Permissions',
+            status: 'pass',
+            message: 'Automation permissions for iTerm2 are granted',
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        if (errorMessage.includes('not allowed') || errorMessage.includes('1743')) {
+            return {
+                name: 'Automation Permissions',
+                status: 'fail',
+                message: 'Automation permissions not granted. Go to System Settings > Privacy & Security > Automation and enable iTerm2 for your terminal/app.',
+            };
+        }
+        // iTerm2 might not be running, which is OK
+        if (errorMessage.includes('not running') ||
+            errorMessage.includes('(-600)')) {
+            return {
+                name: 'Automation Permissions',
+                status: 'warn',
+                message: 'Could not verify automation permissions (iTerm2 is not running). Permissions will be requested on first use.',
+            };
+        }
+        return {
+            name: 'Automation Permissions',
+            status: 'warn',
+            message: `Could not verify automation permissions: ${errorMessage}`,
+        };
+    }
+}
+/**
+ * Check if Node.js version meets requirements
+ */
+export function checkNodeVersion() {
+    const nodeVersion = process.version;
+    const major = parseInt(nodeVersion.slice(1).split('.')[0], 10);
+    if (major >= 18) {
+        return {
+            name: 'Node.js',
+            status: 'pass',
+            message: `Node.js ${nodeVersion} meets minimum requirement (>=18.0.0)`,
+        };
+    }
+    return {
+        name: 'Node.js',
+        status: 'fail',
+        message: `Node.js ${nodeVersion} is below minimum requirement (>=18.0.0)`,
+    };
+}
+/**
+ * Run all environment checks
+ */
+export async function runAllChecks() {
+    const checks = [];
+    // Synchronous checks
+    checks.push(checkMacOS());
+    checks.push(checkNodeVersion());
+    // Async checks
+    checks.push(await checkITerm2());
+    checks.push(await checkClaudeCode());
+    checks.push(await checkAutomationPermissions());
+    const allPassed = checks.every(c => c.status === 'pass' || c.status === 'warn');
+    return { allPassed, checks };
+}
+/**
+ * Format check results for display
+ */
+export function formatCheckResults(result) {
+    const lines = ['Environment Check Results', '='.repeat(50), ''];
+    for (const check of result.checks) {
+        const icon = check.status === 'pass'
+            ? '[OK]'
+            : check.status === 'warn'
+                ? '[!!]'
+                : '[X]';
+        lines.push(`${icon} ${check.name}`);
+        lines.push(`    ${check.message}`);
+        lines.push('');
+    }
+    lines.push('='.repeat(50));
+    if (result.allPassed) {
+        lines.push('All checks passed! Environment is ready.');
+    }
+    else {
+        lines.push('Some checks failed. Please fix the issues above.');
+    }
+    return lines.join('\n');
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { startServer } from './server.js';
+import { spawnClaudeCoder } from './spawn.js';
+import { listItermWindows, formatWindowList } from './iterm.js';
+import { runAllChecks, formatCheckResults } from './check.js';
+const program = new Command();
+program
+    .name('claude-coder-mac-mcp')
+    .description('Spawn Claude Code instances from Claude Desktop via MCP')
+    .version('1.0.0');
+program
+    .command('mcp')
+    .alias('serve')
+    .description('Start the MCP server (for Claude Desktop)')
+    .option('--dangerously-skip-permissions', 'Pass --dangerously-skip-permissions to spawned Claude instances')
+    .action(async (options) => {
+    await startServer({
+        dangerouslySkipPermissions: options.dangerouslySkipPermissions ?? false,
+    });
+});
+program
+    .command('spawn')
+    .description('Test spawning a Claude Code instance in iTerm2')
+    .argument('<prompt>', 'The prompt/task to give to Claude Code')
+    .option('-d, --directory <path>', 'Working directory', process.env.HOME)
+    .option('-t, --title <title>', 'Window title', 'Claude Coder')
+    .option('--dangerously-skip-permissions', 'Pass --dangerously-skip-permissions to the Claude instance')
+    .action(async (prompt, options) => {
+    const skipPerms = options.dangerouslySkipPermissions ?? false;
+    const modeLabel = skipPerms
+        ? 'with --dangerously-skip-permissions'
+        : 'in normal mode';
+    console.log(`Spawning Claude Code instance (${modeLabel})...`);
+    const result = await spawnClaudeCoder({
+        prompt,
+        workingDirectory: options.directory,
+        windowTitle: options.title,
+        dangerouslySkipPermissions: skipPerms,
+    });
+    if (result.success) {
+        console.log('Success!');
+        console.log(`  Window title: ${result.windowTitle}`);
+        console.log(`  Working directory: ${result.workingDirectory}`);
+        console.log(`  Mode: ${modeLabel}`);
+        console.log(`  Prompt: ${result.prompt}`);
+    }
+    else {
+        console.error(`Failed: ${result.error}`);
+        process.exit(1);
+    }
+});
+program
+    .command('list')
+    .alias('ls')
+    .description('List iTerm2 windows and sessions')
+    .action(async () => {
+    const windows = await listItermWindows();
+    console.log(formatWindowList(windows));
+});
+program
+    .command('check')
+    .alias('doctor')
+    .description('Check if the environment is configured correctly')
+    .action(async () => {
+    const result = await runAllChecks();
+    console.log(formatCheckResults(result));
+    if (!result.allPassed) {
+        process.exit(1);
+    }
+});
+program.parse();

package/dist/iterm.d.ts

@@ -0,0 +1,24 @@
+export interface ItermWindow {
+    id: string;
+    sessions: ItermSession[];
+}
+export interface ItermSession {
+    name: string;
+    tty: string;
+}
+/**
+ * Execute an AppleScript and return the result
+ */
+export declare function execAppleScript(script: string): Promise<string>;
+/**
+ * List all iTerm2 windows and their sessions
+ */
+export declare function listItermWindows(): Promise<ItermWindow[]>;
+/**
+ * Parse the window list output from AppleScript
+ */
+export declare function parseWindowList(output: string): ItermWindow[];
+/**
+ * Format window list for display
+ */
+export declare function formatWindowList(windows: ItermWindow[]): string;

package/dist/iterm.js

@@ -0,0 +1,84 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+const execAsync = promisify(exec);
+/**
+ * Execute an AppleScript and return the result
+ */
+export async function execAppleScript(script) {
+    // Escape single quotes for shell
+    const escapedScript = script.replace(/'/g, "'\"'\"'");
+    const { stdout } = await execAsync(`osascript -e '${escapedScript}'`);
+    return stdout;
+}
+/**
+ * List all iTerm2 windows and their sessions
+ */
+export async function listItermWindows() {
+    const appleScript = `
+tell application "iTerm"
+  set output to ""
+  repeat with w in windows
+    set output to output & "WINDOW:" & (id of w) & linefeed
+    repeat with t in tabs of w
+      repeat with s in sessions of t
+        set output to output & "SESSION:" & (name of s) & "|" & (tty of s) & linefeed
+      end repeat
+    end repeat
+  end repeat
+  return output
+end tell
+`;
+    try {
+        const stdout = await execAppleScript(appleScript);
+        return parseWindowList(stdout);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Parse the window list output from AppleScript
+ */
+export function parseWindowList(output) {
+    const windows = [];
+    let currentWindow = null;
+    const lines = output.split('\n').filter(line => line.trim());
+    for (const line of lines) {
+        if (line.startsWith('WINDOW:')) {
+            if (currentWindow) {
+                windows.push(currentWindow);
+            }
+            currentWindow = {
+                id: line.substring(7),
+                sessions: [],
+            };
+        }
+        else if (line.startsWith('SESSION:') && currentWindow) {
+            const parts = line.substring(8).split('|');
+            currentWindow.sessions.push({
+                name: parts[0] || '',
+                tty: parts[1] || '',
+            });
+        }
+    }
+    if (currentWindow) {
+        windows.push(currentWindow);
+    }
+    return windows;
+}
+/**
+ * Format window list for display
+ */
+export function formatWindowList(windows) {
+    if (windows.length === 0) {
+        return 'No iTerm2 windows found.';
+    }
+    const lines = [];
+    for (const window of windows) {
+        lines.push(`Window: ${window.id}`);
+        for (const session of window.sessions) {
+            lines.push(`  Session: ${session.name} - ${session.tty}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/server.d.ts

@@ -0,0 +1,16 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export interface ServerOptions {
+    dangerouslySkipPermissions: boolean;
+}
+/**
+ * Create and configure the MCP server
+ */
+export declare function createServer(options: ServerOptions): McpServer;
+/**
+ * Register all MCP tools on the server
+ */
+export declare function registerTools(server: McpServer, options: ServerOptions): void;
+/**
+ * Start the MCP server with stdio transport
+ */
+export declare function startServer(options: ServerOptions): Promise<void>;

package/dist/server.js

@@ -0,0 +1,142 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { spawnClaudeCoder } from './spawn.js';
+import { listItermWindows, formatWindowList } from './iterm.js';
+/**
+ * Create and configure the MCP server
+ */
+export function createServer(options) {
+    const server = new McpServer({
+        name: 'claude-coder-mac-mcp',
+        version: '1.0.0',
+    });
+    registerTools(server, options);
+    return server;
+}
+/**
+ * Register all MCP tools on the server
+ */
+export function registerTools(server, options) {
+    const { dangerouslySkipPermissions } = options;
+    const permissionMode = dangerouslySkipPermissions
+        ? 'AUTONOMOUS MODE (--dangerously-skip-permissions): Claude will act without user approval. Be specific to prevent unintended actions.'
+        : 'INTERACTIVE MODE: User must approve each action in the spawned terminal.';
+    const toolDescription = `Spawn a new Claude Code instance in an iTerm2 window to work on a task.
+
+${permissionMode}
+
+PROMPT BEST PRACTICES:
+- Be specific: "Run npm test, fix any failing tests" not "fix tests"
+- Include context Claude can't see: "This is a Next.js app using Prisma and PostgreSQL"
+- Set success criteria: "Done when all tests pass and npm run build succeeds"
+- Mention key files: "The API routes are in src/app/api/"
+- One focused task works better than multiple vague ones
+
+EXAMPLE PROMPT:
+"In this TypeScript Express project, add a new GET /api/health endpoint that returns {status: 'ok', timestamp: Date.now()}. Follow the pattern in src/routes/users.ts. Run npm test when done."
+
+ALWAYS specify workingDirectory so Claude starts in the correct project folder. If you do not know the correct working directory, specify as the first instruction in your prompt that claude should find the project and cd into its directory first.`;
+    server.registerTool('spawn_claude_coder', {
+        title: 'Spawn Claude Coder',
+        description: toolDescription,
+        inputSchema: {
+            prompt: z
+                .string()
+                .describe('The prompt/task to give to the new Claude Code instance'),
+            workingDirectory: z
+                .string()
+                .optional()
+                .describe('The working directory for the Claude Code instance (defaults to home directory)'),
+            windowTitle: z
+                .string()
+                .optional()
+                .describe("Custom title for the iTerm2 window (defaults to 'Claude Coder')"),
+        },
+        annotations: {
+            title: 'Spawn Claude Coder',
+            readOnlyHint: false,
+            destructiveHint: dangerouslySkipPermissions,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ prompt, workingDirectory, windowTitle }) => {
+        const result = await spawnClaudeCoder({
+            prompt,
+            workingDirectory,
+            windowTitle,
+            dangerouslySkipPermissions,
+        });
+        if (result.success) {
+            const permissionStatus = result.dangerouslySkipPermissions
+                ? 'with --dangerously-skip-permissions'
+                : 'in normal mode';
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Successfully spawned Claude Code in iTerm2 (${permissionStatus})!\n\nWindow title: ${result.windowTitle}\nWorking directory: ${result.workingDirectory}\nPrompt: ${result.prompt}\n\nThe Claude Code instance is now running interactively in iTerm2.`,
+                    },
+                ],
+            };
+        }
+        else {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to spawn Claude Code: ${result.error}\n\nMake sure iTerm2 is installed and you have granted automation permissions in System Settings > Privacy & Security > Automation.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool('list_iterm_windows', {
+        title: 'List iTerm2 Windows',
+        description: 'List all iTerm2 windows and their sessions (useful to see running Claude instances)',
+        annotations: {
+            title: 'List iTerm2 Windows',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async () => {
+        try {
+            const windows = await listItermWindows();
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: formatWindowList(windows),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Failed to list iTerm windows: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+/**
+ * Start the MCP server with stdio transport
+ */
+export async function startServer(options) {
+    const server = createServer(options);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const modeLabel = options.dangerouslySkipPermissions
+        ? 'with --dangerously-skip-permissions'
+        : 'in normal mode';
+    console.error(`Claude Coder Mac MCP server running on stdio (${modeLabel})`);
+}

package/dist/spawn.d.ts

@@ -0,0 +1,38 @@
+export interface SpawnOptions {
+    prompt: string;
+    workingDirectory?: string;
+    windowTitle?: string;
+    dangerouslySkipPermissions?: boolean;
+}
+export interface SpawnResult {
+    success: boolean;
+    windowTitle: string;
+    workingDirectory: string;
+    prompt: string;
+    dangerouslySkipPermissions: boolean;
+    error?: string;
+}
+/**
+ * Escape a string for use in AppleScript
+ */
+export declare function escapeForAppleScript(str: string): string;
+/**
+ * Escape a string for use in shell (inside the AppleScript command)
+ */
+export declare function escapeForShell(str: string): string;
+/**
+ * Build the claude command string
+ */
+export declare function buildClaudeCommand(prompt: string, dangerouslySkipPermissions: boolean): string;
+/**
+ * Build the full shell command (cd + claude)
+ */
+export declare function buildFullCommand(prompt: string, workingDirectory: string, dangerouslySkipPermissions: boolean): string;
+/**
+ * Build the AppleScript to spawn an iTerm2 window with a command
+ */
+export declare function buildSpawnAppleScript(command: string, windowTitle: string): string;
+/**
+ * Spawn a new Claude Code instance in iTerm2
+ */
+export declare function spawnClaudeCoder(options: SpawnOptions): Promise<SpawnResult>;

package/dist/spawn.js

@@ -0,0 +1,76 @@
+import { execAppleScript } from './iterm.js';
+/**
+ * Escape a string for use in AppleScript
+ */
+export function escapeForAppleScript(str) {
+    return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+}
+/**
+ * Escape a string for use in shell (inside the AppleScript command)
+ */
+export function escapeForShell(str) {
+    // Use single quotes and escape any single quotes in the string
+    return `'${str.replace(/'/g, "'\"'\"'")}'`;
+}
+/**
+ * Build the claude command string
+ */
+export function buildClaudeCommand(prompt, dangerouslySkipPermissions) {
+    const flags = dangerouslySkipPermissions
+        ? '--dangerously-skip-permissions '
+        : '';
+    return `claude ${flags}${escapeForShell(prompt)}`;
+}
+/**
+ * Build the full shell command (cd + claude)
+ */
+export function buildFullCommand(prompt, workingDirectory, dangerouslySkipPermissions) {
+    const claudeCommand = buildClaudeCommand(prompt, dangerouslySkipPermissions);
+    return `cd ${escapeForShell(workingDirectory)} && ${claudeCommand}`;
+}
+/**
+ * Build the AppleScript to spawn an iTerm2 window with a command
+ */
+export function buildSpawnAppleScript(command, windowTitle) {
+    return `
+tell application "iTerm"
+  activate
+  set newWindow to (create window with default profile)
+  tell current session of newWindow
+    set name to "${escapeForAppleScript(windowTitle)}"
+    write text "${escapeForAppleScript(command)}"
+  end tell
+end tell
+`;
+}
+/**
+ * Spawn a new Claude Code instance in iTerm2
+ */
+export async function spawnClaudeCoder(options) {
+    const windowTitle = options.windowTitle || 'Claude Coder';
+    const workingDirectory = options.workingDirectory || process.env.HOME || '~';
+    const dangerouslySkipPermissions = options.dangerouslySkipPermissions ?? false;
+    const fullCommand = buildFullCommand(options.prompt, workingDirectory, dangerouslySkipPermissions);
+    const appleScript = buildSpawnAppleScript(fullCommand, windowTitle);
+    try {
+        await execAppleScript(appleScript);
+        return {
+            success: true,
+            windowTitle,
+            workingDirectory,
+            prompt: options.prompt,
+            dangerouslySkipPermissions,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            windowTitle,
+            workingDirectory,
+            prompt: options.prompt,
+            dangerouslySkipPermissions,
+            error: errorMessage,
+        };
+    }
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "claude-coder-mac-mcp",
+  "version": "1.0.0",
+  "description": "MCP server to spawn Claude Code instances in iTerm2",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "claude-coder-mac-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "start": "node dist/index.js",
+    "lint": "gts lint",
+    "fix": "gts fix",
+    "clean": "gts clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepare": "npm run build",
+    "pretest": "npm run build",
+    "posttest": "npm run lint",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "iterm2",
+    "macos",
+    "terminal",
+    "automation"
+  ],
+  "author": "pm990320",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pm990320/claude-coder-mac-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pm990320/claude-coder-mac-mcp/issues"
+  },
+  "homepage": "https://github.com/pm990320/claude-coder-mac-mcp#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "commander": "^14.0.3",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "eslint-plugin-security": "^3.0.1",
+    "gts": "^7.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}