💻 shell-mcp

MCP Server for secure shell command execution with whitelist support.

Features

Core Operations

• ⚡ run_command - Execute shell commands
• 📋 get_logs - Retrieve command logs
• ❌ cancel_command - Cancel running command
• 📊 get_command_status - Check command status
• 📝 list_presets - List available command presets

Security Features

• Command whitelist
• Configurable allowed commands
• Timeout management
• Working directory restrictions
• Command output streaming

Predefined Presets

• PHP: composer install, composer update, phpstan analyse, phpunit
• Node.js: npm install, npm run build, npm test
• Docker: docker ps, docker-compose up, docker-compose down
• Git: git status, git log, git diff

Installation

npm install @customable/shell-mcp

Or install from Forgejo Package Registry:

# Add to your .npmrc
echo "@customable:registry=https://git.customable.host/api/packages/customable-mcp/npm/" >> .npmrc

# Install
npm install @customable/shell-mcp

Configuration

Add to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "shell-mcp": {
      "command": "node",
      "args": ["/path/to/node_modules/@customable/shell-mcp/dist/index.js"],
      "env": {
        "ALLOWED_COMMANDS": "npm,composer,git,docker",
        "COMMAND_TIMEOUT": "300000"
      }
    }
  }
}

Environment Variables

• ALLOWED_COMMANDS - Comma-separated list of allowed commands (e.g., "npm,composer,git")
• ALLOWED_DIRS - Comma-separated list of allowed working directories
• COMMAND_TIMEOUT - Command timeout in milliseconds (default: 300000 = 5min)

Usage

Once configured, the MCP server will be available in Claude Code. You can use tools like:

run_command, get_logs, cancel_command, get_command_status, list_presets

Security

⚠️ Important: Only use this MCP in trusted environments. Command execution can be dangerous if not properly configured.

License

MIT