# Safe Terminal MCP Server

A secure, controlled terminal MCP server with strict command whitelisting and multiple safety layers.

## 🛡️ Security Features

- **Command Whitelisting**: Only pre-approved commands are allowed
- **Pattern Blocking**: Blocks shell metacharacters and dangerous patterns
- **Path Sanitization**: Prevents directory traversal attacks
- **Dangerous Command Control**: Requires explicit permission for risky commands
- **Resource Limits**: Timeouts and output size limits
- **File Type Restrictions**: Only safe file extensions allowed

## 🚀 Quick Setup

### 1. Install Dependencies
```bash
npm install
```

### 2. Build Project
```bash
npm run build
```

### 3. Test
```bash
npm start
```

## 📁 Project Structure
```
safe-terminal-mcp/
├── src/
│   └── index.ts          # Main server code
├── dist/                 # Compiled JavaScript (generated)
├── package.json          # Project dependencies
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file
```

## 🔧 Configuration

### Safe Commands (Built-in)
- **Read-only**: `ls`, `pwd`, `cat`, `head`, `tail`, `find`, `grep`, `wc`
- **System info**: `date`, `whoami`, `uname`, `df`, `free`, `uptime`
- **Development**: `git`, `npm`, `node`, `python` (requires allowDangerous)

### Dangerous Commands
These require `allowDangerous: true`:
- File modification: `touch`, `mkdir`, `cp`, `mv`, `rm`
- Network access: `ping`, `curl`, `wget`
- Code execution: `node`, `python`, `npm`
- System changes: `chmod`, `chown`

## 🔌 Claude Desktop Integration

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "safe-terminal": {
      "command": "node",
      "args": ["/absolute/path/to/safe-terminal-mcp/dist/index.js"]
    }
  }
}
```

## 🔨 Available Tools

### 1. `run_safe_command`
Execute whitelisted commands with safety checks.

**Parameters:**
- `command` (required): The command to execute
- `allowDangerous` (optional): Allow dangerous commands (default: false)
- `workingDir` (optional): Working directory (relative to server root)

**Example:**
```json
{
  "command": "ls -la",
  "allowDangerous": false,
  "workingDir": "src"
}
```

### 2. `list_safe_commands`
List all available commands and their danger levels.

### 3. `read_file`
Safely read text files with extension checking.

**Parameters:**
- `path` (required): File path to read

### 4. `list_directory`
List directory contents safely.

**Parameters:**
- `path` (optional): Directory path (default: current directory)

## 🛡️ Safety Features Explained

### Command Whitelisting
Only pre-approved commands in `SAFE_COMMANDS` are allowed. Each command is categorized as safe or dangerous.

### Pattern Blocking
Blocks dangerous shell patterns:
- Shell metacharacters: `;`, `&`, `|`, `` ` ``, `$`, `()`, `{}`
- Directory traversal: `..`
- System directories: `/etc/`, `/var/`, `/usr/bin/`
- Privilege escalation: `sudo`, `su`
- File redirection: `>`, `<`

### Path Sanitization
All file paths are resolved and checked to ensure they stay within the working directory.

### Resource Limits
- **Timeout**: 30 seconds max execution time
- **Output**: 1MB max output size
- **File size**: Files truncated at 1MB

## 🧪 Testing

Test the server manually:
```bash
# Start the server
npm start

# In another terminal, test with MCP inspector
npx @modelcontextprotocol/inspector node dist/index.js
```

## 🔐 Security Best Practices

1. **Run in Isolation**: Use in a sandboxed environment or VM
2. **Monitor Commands**: Review all command executions
3. **Limit Dangerous Commands**: Only enable when absolutely necessary
4. **Regular Updates**: Keep dependencies updated
5. **Principle of Least Privilege**: Only grant necessary permissions

## ⚠️ Important Notes

- This is much safer than unrestricted terminal access, but still carries risks
- Dangerous commands should only be enabled when necessary
- Always review commands before execution in production
- Consider running in a containerized environment for additional isolation

## 🔄 Customization

You can easily customize the server by:
- Adding new safe commands to `SAFE_COMMANDS`
- Modifying `DANGEROUS_PATTERNS` for additional blocking
- Adjusting resource limits in `CONFIG`
- Adding new tools for specific use cases