macOS Shell MCP Server

An MCP server for shell command execution on macOS with session management, background processes, caching, and semantic search.

Installation

git clone https://github.com/quanticsoul4772/macos-shell.git
cd macos-shell
npm install
npm run build

Related MCP server: SSH MCP Server

Configuration

Claude Code

Add to ~/.claude.json under mcpServers:

{
  "macos-shell": {
    "type": "stdio",
    "command": "node",
    "args": ["/path/to/macos-shell/build/server.js"],
    "env": {
      "VOYAGE_API_KEY": "your-voyage-api-key"
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "macos-shell": {
      "command": "node",
      "args": ["/path/to/macos-shell/build/server.js"],
      "env": {
        "VOYAGE_API_KEY": "your-voyage-api-key"
      }
    }
  }
}

The VOYAGE_API_KEY enables semantic search features. Without it, set "EMBEDDINGS_ENABLED": "false" instead.

Tools (41)

Command execution (3)

• run_command -- execute a shell command

• run_script -- execute a multi-line shell script

• batch_execute_enhanced -- execute commands with conditional logic and retries

Sessions (3)

• create_shell_session -- create a named session with isolated environment

• list_shell_sessions -- list active sessions

• close_session -- close a session and free resources

Navigation and environment (5)

• cd -- change working directory

• pwd -- get current working directory

• set_env -- set environment variables

• get_env -- get environment variables

• history -- view command history

Background processes (8)

• run_background -- start a background process

• list_processes -- list processes with resource usage

• get_process_output -- retrieve output with search

• stream_process_output -- stream output as it arrives

• kill_process -- terminate a process

• cleanup_orphans -- manage processes from previous sessions

• kill_all_matching -- kill processes matching a pattern

• save_process_output -- save output to a file

System (3)

• get_system_health -- system health metrics

• preflight_check -- validate conditions before operations

• system_profile -- gather system information

SSH (8)

• ssh_interactive_start -- start an SSH session

• ssh_interactive_send -- send input to SSH session

• ssh_interactive_control -- send control characters

• ssh_interactive_output -- get output with search

• ssh_interactive_wait -- wait for new output

• ssh_interactive_resize -- resize terminal

• ssh_interactive_close -- close SSH session

• ssh_interactive_list -- list active SSH sessions

Cache management (5)

• cache_stats -- cache statistics

• cache_clear_command -- clear specific command from cache

• cache_clear_pattern -- clear commands matching a pattern

• cache_mark_never -- mark a command to never cache

• cache_explain -- explain cache decision for a command

Semantic search (6)

Requires VOYAGE_API_KEY. See docs/SEMANTIC_SEARCH.md for details.

• semantic_command_search -- search command history by intent

• search_documentation -- search command docs semantically

• recommend_commands -- get suggestions based on intent

• error_solution_lookup -- find solutions for error messages

• analyze_output -- extract patterns from command output

• semantic_search_stats -- search system statistics

Environment variables

Limitations

• macOS only (uses /bin/zsh)

• 30-second default command timeout (configurable up to 10 minutes)

• Commands run with the permissions of the user running the MCP client

• Output buffer limited to 300 lines per background process

• Sudo commands require passwordless sudo or will hang

Further documentation

• Changelog

• Semantic search

• Cache system

• Testing

Development

See CLAUDE.md for build commands, architecture, testing, and contribution details.

License

ISC