shell-proxy-mcp

A Model Context Protocol (MCP) server that provides shell proxy functionality. Define your shell tools in YAML and expose them to LLMs through MCP.

Features

• YAML Configuration: Define shell tools with parameters, types, and descriptions in a simple YAML format
• Type Validation: Automatic runtime parameter validation using Zod schemas (string, number, boolean)
• Template Support: Use Mustache templates ({{param}}) for dynamic command generation
• Security: Built-in parameter validation, configurable timeouts, and error handling
• Cross-platform: Works on Linux, macOS, and Windows with platform-specific shell support
• Flexible Execution: Configure shell type and timeout per tool or globally
• Rich Output: Optional output prefixes and structured error reporting

Requirements

• Node.js 20.x or 22.x

Installation

Using npx (Recommended)

The easiest way to use shell-proxy-mcp is with npx - no installation required:

npx @mileschou/shell-proxy-mcp path/to/your/tools.yaml

From npm

Install globally:

npm install -g @mileschou/shell-proxy-mcp
shell-proxy-mcp path/to/your/tools.yaml

From Source

For development or customization:

git clone https://github.com/MilesChou/shell-proxy-mcp.git
cd shell-proxy-mcp
npm install
npm run build
node dist/index.js path/to/your/tools.yaml

Usage with Claude Desktop

Using npx (Recommended)

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "shell-proxy": {
      "command": "npx",
      "args": [
        "-y",
        "@mileschou/shell-proxy-mcp",
        "/path/to/your/tools.yaml"
      ]
    }
  }
}

Note: The -y flag automatically confirms the installation prompt.

Using Global Installation

If you installed globally with npm:

{
  "mcpServers": {
    "shell-proxy": {
      "command": "shell-proxy-mcp",
      "args": [
        "/path/to/your/tools.yaml"
      ]
    }
  }
}

Using Local Build

If building from source:

{
  "mcpServers": {
    "shell-proxy": {
      "command": "node",
      "args": [
        "/path/to/shell-proxy-mcp/dist/index.js",
        "/path/to/your/tools.yaml"
      ]
    }
  }
}

Configuration

Create a tools.yaml file to define your shell tools:

mcp:
  description: My shell tools
  run:
    shell: /bin/bash
    timeout: 30000  # milliseconds

  tools:
    - name: list_files
      description: List files in a directory
      params:
        directory:
          type: string
          description: Directory path to list
          required: true
        pattern:
          type: string
          description: File pattern to match
          required: false
          default: "*"
      run:
        command: ls -la "{{directory}}" | grep "{{pattern}}"
      output:
        prefix: "Files in {{directory}}:"

    - name: disk_usage
      description: Show disk usage
      params:
        directory:
          type: string
          required: true
        max_depth:
          type: number
          required: false
          default: 1
      run:
        command: du -h --max-depth={{max_depth}} "{{directory}}"

Configuration Reference

Parameter Types:

• string: Text values
• number: Numeric values
• boolean: true/false values

Parameter Options:

• required: Whether the parameter is mandatory
• default: Default value if not provided
• description: Parameter description for LLMs

Tool Options:

• run.command: Shell command with Mustache templates
• run.shell: Override default shell (optional)
• run.timeout: Override default timeout in ms (optional)
• output.prefix: Add prefix to command output (optional)

Environment Variables

The following environment variables can be used to customize server behavior:

• SHELL_PROXY_MCP_TIMEOUT_MS - Default command timeout in milliseconds (default: 30000)
• SHELL_PROXY_MCP_MAX_BUFFER - Maximum output buffer size in bytes (default: 10485760)
• SHELL_PROXY_MCP_TIMEOUT_EXIT_CODE - Exit code for timeout errors (default: 124)
• SHELL_PROXY_MCP_UNIX_SHELL - Default shell for Unix/Linux/macOS (default: /bin/bash)
• SHELL_PROXY_MCP_WIN32_SHELL - Default shell for Windows (default: cmd.exe)

Example:

# Set custom timeout (60 seconds)
export SHELL_PROXY_MCP_TIMEOUT_MS=60000

# Set custom buffer size (20MB)
export SHELL_PROXY_MCP_MAX_BUFFER=20971520

# Use zsh as default shell on Unix
export SHELL_PROXY_MCP_UNIX_SHELL=/bin/zsh

# Run the server
npx @mileschou/shell-proxy-mcp tools.yaml

Using with Claude Desktop:

You can set environment variables in the Claude Desktop configuration:

{
  "mcpServers": {
    "shell-proxy": {
      "command": "npx",
      "args": ["-y", "@mileschou/shell-proxy-mcp", "/path/to/tools.yaml"],
      "env": {
        "SHELL_PROXY_MCP_TIMEOUT_MS": "60000",
        "SHELL_PROXY_MCP_UNIX_SHELL": "/bin/zsh"
      }
    }
  }
}

Examples

The examples directory contains comprehensive tool configurations:

• examples/tools.yaml: 6 ready-to-use tools demonstrating different patterns:

  • list_files: Directory listing with pattern filtering
  • disk_usage: Disk space analysis with configurable depth
  • find_large_files: Find files above a size threshold
  • system_info: System information gathering
  • git_status: Git repository status checker
  • count_lines: Code line counting by file extension

• examples/README.md: Detailed documentation including:

  • Complete parameter reference for each tool
  • Usage examples with different parameter combinations
  • Best practices for creating custom tools
  • Security considerations
  • Cross-platform compatibility tips
  • Testing and debugging guide

Quick Example

Try the example tools:

Using npx (no installation required):

npx @mileschou/shell-proxy-mcp examples/tools.yaml

Or build from source:

# Clone and build
git clone https://github.com/MilesChou/shell-proxy-mcp.git
cd shell-proxy-mcp
npm install
npm run build

# Run with example configuration
node dist/index.js examples/tools.yaml

Then configure in Claude Desktop to start using the tools with your LLM.

CLI Usage

Using npx (no installation):

# With config file
npx @mileschou/shell-proxy-mcp path/to/tools.yaml

# Show help
npx @mileschou/shell-proxy-mcp --help

If installed globally:

# Use tools.yaml in current directory
shell-proxy-mcp

# Specify configuration file
shell-proxy-mcp path/to/config.yaml

# Show help
shell-proxy-mcp --help

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode for development
npm run watch

# Run tests (32 tests covering config, validator, executor)
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with UI
npm run test:ui

# Generate coverage report
npm run test:coverage

Project Structure

src/
├── config.ts      # YAML configuration parser
├── validator.ts   # Parameter validation with Zod
├── executor.ts    # Command execution with Mustache templates
├── server.ts      # MCP server implementation
└── index.ts       # CLI entry point

tests/
├── config.test.ts    # Configuration tests
├── validator.test.ts # Validation tests
├── executor.test.ts  # Execution tests
└── fixtures/         # Test YAML files

examples/
├── tools.yaml    # Example tool configurations
└── README.md     # Detailed examples documentation

Use Cases

This MCP server enables LLMs to safely execute system commands for various tasks:

• System Administration: Check disk usage, list files, monitor processes
• Development: Git operations, line counting, file searching
• Data Analysis: Log parsing, file statistics, directory analysis
• Automation: Create custom tools for repetitive shell tasks
• Monitoring: System information, resource usage, service status

Supported Operating Systems

Tested and working on:

• Ubuntu (latest) - Full support
• macOS (latest) - Full support
• Windows (latest) - Full support with cmd.exe or PowerShell

CI/CD runs tests on Node.js 20.x and 22.x across all platforms.

Inspiration

This project is inspired by MCPShell (Go implementation) and provides a Node.js/TypeScript alternative with:

• Native TypeScript support
• Zod-based validation
• Vitest testing framework
• Cross-platform compatibility

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Areas for improvement:

• Additional example tools
• Enhanced security features (CEL-like constraints)
• Better error messages
• Platform-specific optimizations
• Documentation improvements

Please feel free to submit a Pull Request or open an issue.

Support

• Documentation: Check examples/README.md for detailed guides
• Issues: Report bugs at GitHub Issues
• MCP Resources: Visit Model Context Protocol for more information