PermShell

PermShell MCP lets you execute shell commands with explicit permission prompts, enabling safe, guided automation through a Model Context Protocol client. It transparently shows what will run and requires user consent before each action, helping you automate tasks while preserving control over system commands.

How to use

You interact with PermShell MCP through an MCP client. Start the local server, then connect your client to request command execution. When you ask the system to run a command, PermShell MCP requests a visible permission dialog that lists the commands and the working directory. If you approve, the command runs and you receive the results. You can execute typical shell tasks like listing files, inspecting system information, or chaining commands, all while keeping explicit permission checks in place.

To use the built-in tools, reference the available capabilities in your MCP client. For example, you can trigger a command to list files in a directory or retrieve system information. Each operation shows the exact commands that will be executed and requires your approval before proceeding.

How to install

Prerequisites: you need Node.js and npm installed on your machine.

# Clone the repository
git clone https://github.com/yourusername/perm-shell-mcp.git
cd perm-shell-mcp

# Install dependencies
npm install

# Build the project
npm run build

Additional notes

You can run PermShell MCP as a standalone tool or integrate it with Claude Desktop by providing a server entry that points to the local build. The standalone start command runs the MCP server directly, while the Claude configuration connects to the locally running process.

{
  "mcpServers": {
    "permshell": {
      "command": "node",
      "args": ["/path/to/perm-shell-mcp/dist/index.js"]
    }
  }
}

Security is designed around explicit user consent. Every command requires permission, the command details include the working directory, there are safeguards to prevent runaway processes, and input sanitization reduces the risk of command injection.

Security

• All commands require explicit permission through desktop notifications. - Commands display with their working directory for full transparency. - Timeout limits prevent runaway processes. - Input sanitization reduces command injection risks.

Troubleshooting

If you encounter issues starting the server, verify you have Node.js installed and that the build completed successfully. Ensure the path in the Claude Desktop configuration points to the built index.js file under dist. Check that npm install completed without errors and that the server process starts with the provided start commands.

Available tools

execute-command

Executes a shell command with permission, returning output after the user approves the operation.

system-info

Retrieves system information such as OS, uptime, memory, disk usage, and CPU details.