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

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

Variable	Description
VOYAGE_API_KEY	Voyage AI API key for semantic search
EMBEDDINGS_ENABLED	Set to false to disable semantic search
MCP_DISABLE_CACHE	Set to true to disable command caching
MCP_DEBUG	Set to true for debug logging to stderr
MCP_LOG_FILE	Path to write log output

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