Secure Shell Executor

🚀 MCP Shell Server

A secure server for executing authorized shell commands and supporting input via stdin. This server implements the Model Context Protocol (MCP), enabling remote execution of verified shell commands.

🚀 Quick Start

Client Configuration in Claude.app

Release Version

code ~/Library/Application\ Support/Claude/claude.yaml

backend:
  class: mcp_shell_server.Backend
  config:
    server_uri: http://localhost:5000
    max_timeout: 3600

Local Version

poetry install
poetry run mcp-shell-server

Installation Instructions

Install Dependencies

pip install -e ".[test]"

Start the Server

uvicorn main:app --reload

Verify Installation

Run the following command to check if the installation was successful:

mcp-shell-server --version

✨ Features

• Secure Command Execution: Only trusted commands are allowed to be executed.
• Standard Input Support: Input can be provided to commands via stdin.
• Comprehensive Output: Returns stdout, stderr, exit status code, and execution time.
• Shell Operator Verification: Command verification is still required when using shell operators (;, &&, ||, |).
• Timeout Control: Set a maximum execution time for commands.

💻 Usage Examples

Example 1: Execute a Basic Command

Request Example

{
  "command": ["echo", "Hello, World!"],
  "stdin": null,
  "directory": "/",
  "timeout": 30
}

Response Example

{
  "stdout": "Hello, World!\n",
  "stderr": "",
  "status": 0,
  "execution_time": 0.123456
}

Example 2: Command with Standard Input

Request Example

{
  "command": ["tr", "a-z", "A-Z"],
  "stdin": "hello world\n",
  "directory": "/tmp",
  "timeout": 60
}

📚 Documentation

Request Format

Request Parameters

Response Format

Development Instructions

Set Up the Development Environment

1. Clone the repository

git clone https://github.com/yourusername/mcp-shell-server.git
cd mcp-shell-server

2. Install dependencies (including test requirements)

pip install -e ".[test]"

Execute Tests

pytest

📄 API Documentation

Request Parameters

Response Parameters

🔧 Technical Details

System Requirements

• Python 3.11 or higher
• mcp >= 1.1.0

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.