https://github.com/tumf/mcp-shell-server
https://github.com/tumf/mcp-shell-server
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/tumf/mcp-shell-server
- Owner: tumf
- License: mit
- Created: 2024-12-10T13:09:04.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-01-05T01:04:54.000Z (3 months ago)
- Last Synced: 2025-02-27T21:36:02.164Z (about 2 months ago)
- Language: Python
- Size: 175 KB
- Stars: 21
- Watchers: 2
- Forks: 8
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-list - tumf/mcp-shell-server - shell-server?style=social)](https://github.com/tumf/mcp-shell-server): Securely executes shell commands through the Model Context Protocol. (Uncategorized / Uncategorized)
- awesome-mcp-servers - tumf/mcp-shell-server
- awesome-mcp-servers - tumf/mcp-shell-server
- awesome-mcp-servers - tumf/mcp-shell-server
- awesome-mcp-servers - MCP Shell Executor - Securely executes whitelisted shell commands remotely via the Model Context Protocol (MCP), providing stdin support and detailed output (Table of Contents / System Automation)
- awesome-mcp-servers - MCP Shell Executor - Securely executes whitelisted shell commands remotely via the Model Context Protocol (MCP), providing stdin support and detailed output (Table of Contents / System Automation)
README
# MCP Shell Server
[](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