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

npm install

2. Build Project

npm run build

3. Test

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):

{
  "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:

{
  "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:

# 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