Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/tumf/mcp-shell-server


https://github.com/tumf/mcp-shell-server

Last synced: 8 months ago
JSON representation

Awesome Lists containing this project

README 

          
# MCP Shell Server



[![codecov](https://codecov.io/gh/tumf/mcp-shell-server/branch/main/graph/badge.svg)](https://codecov.io/gh/tumf/mcp-shell-server)



A secure shell command execution server implementing the Model Context Protocol (MCP). This server allows remote execution of whitelisted shell commands with support for stdin input.



## Features



* **Secure Command Execution**: Only whitelisted commands can be executed

* **Standard Input Support**: Pass input to commands via stdin

* **Comprehensive Output**: Returns stdout, stderr, exit status, and execution time

* **Shell Operator Safety**: Validates commands after shell operators (; , &&, ||, |)

* **Timeout Control**: Set maximum execution time for commands



## MCP client setting in your Claude.app



### Published version



```shell

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

```



```json

{

  "mcpServers": {

    "shell": {

      "command": "uvx",

      "args": [

        "mcp-shell-server"

      ],

      "env": {

        "ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"

      }

    },

  }

}

```



### Local version



#### Configuration



```shell

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

```



```json

{

  "mcpServers": {

    "shell": {

      "command": "uv",

      "args": [

        "--directory",

        ".",

        "run",

        "mcp-shell-server"

      ],

      "env": {

        "ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"

      }

    },

  }

}

```



#### Installation



```bash

pip install mcp-shell-server

```



## Usage



### Starting the Server



```bash

ALLOW_COMMANDS="ls,cat,echo" uvx mcp-shell-server

# Or using the alias

ALLOWED_COMMANDS="ls,cat,echo" uvx mcp-shell-server

```



The `ALLOW_COMMANDS` (or its alias `ALLOWED_COMMANDS` ) environment variable specifies which commands are allowed to be executed. Commands can be separated by commas with optional spaces around them.



Valid formats for ALLOW_COMMANDS or ALLOWED_COMMANDS:



```bash

ALLOW_COMMANDS="ls,cat,echo"          # Basic format

ALLOWED_COMMANDS="ls ,echo, cat"      # With spaces (using alias)

ALLOW_COMMANDS="ls,  cat  , echo"     # Multiple spaces

```



### Request Format



```python

# Basic command execution

{

    "command": ["ls", "-l", "/tmp"]

}



# Command with stdin input

{

    "command": ["cat"],

    "stdin": "Hello, World!"

}



# Command with timeout

{

    "command": ["long-running-process"],

    "timeout": 30  # Maximum execution time in seconds

}



# Command with working directory and timeout

{

    "command": ["grep", "-r", "pattern"],

    "directory": "/path/to/search",

    "timeout": 60

}

```



### Response Format



Successful response:



```json

{

    "stdout": "command output",

    "stderr": "",

    "status": 0,

    "execution_time": 0.123

}

```



Error response:



```json

{

    "error": "Command not allowed: rm",

    "status": 1,

    "stdout": "",

    "stderr": "Command not allowed: rm",

    "execution_time": 0

}

```



## Security



The server implements several security measures:



1. **Command Whitelisting**: Only explicitly allowed commands can be executed

2. **Shell Operator Validation**: Commands after shell operators (;, &&, ||, |) are also validated against the whitelist

3. **No Shell Injection**: Commands are executed directly without shell interpretation



## Development



### Setting up Development Environment



1. Clone the repository



```bash

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

cd mcp-shell-server

```



2. Install dependencies including test requirements



```bash

pip install -e ".[test]"

```



### Running Tests



```bash

pytest

```



## API Reference



### Request Arguments



| Field     | Type       | Required | Description                                   |

|-----------|------------|----------|-----------------------------------------------|

| command   | string[]   | Yes      | Command and its arguments as array elements   |

| stdin     | string     | No       | Input to be passed to the command            |

| directory | string     | No       | Working directory for command execution       |

| timeout   | integer    | No       | Maximum execution time in seconds             |



### Response Fields



| Field           | Type    | Description                                |

|----------------|---------|---------------------------------------------|

| stdout         | string  | Standard output from the command           |

| stderr         | string  | Standard error output from the command     |

| status         | integer | Exit status code                           |

| execution_time | float   | Time taken to execute (in seconds)         |

| error          | string  | Error message (only present if failed)     |



## Requirements



* Python 3.11 or higher

* mcp>=1.1.0



## License



MIT License - See LICENSE file for details