The command-executor MCP server provides a secure, MCP-driven interface for executing pre-approved shell commands. It enforces a configurable allowlist of commands and validates each request to prevent injection or unauthorized actions. Clients interact with the server via the MCP tool API, sending an execute_command request with a selected pre-approved command. The server streams output back to the client in real time, enabling you to monitor progress and results without opening a separate terminal. This makes it suitable for automation pipelines and integrated tooling where command execution must be tightly controlled.

With the built-in tool API, you can perform actions such as running git status, listing directory contents, or invoking npm scripts, provided those commands are included in the ALLOWED_COMMANDS list. You can customize the allowed commands through the ALLOWED_COMMANDS environment variable to tailor the capabilities to your security and workflow requirements. The server runs in its own isolated environment and sanitizes environment variables to minimize risk. For debugging, you can use the MCP Inspector tool to connect to the MCP server and inspect requests and responses in your browser.

Prerequisites:

• Node.js (preferably LTS) and npm installed on your system
• Basic familiarity with MCP workflow and environment variables

Step-by-step installation:

1. Install dependencies npm install

2. Build the server (TypeScript to JavaScript) npm run build

3. (Optional) Run in development with auto-rebuild npm run watch

4. (Optional) Start the server directly for testing node /path/to/command-executor/build/index.js

5. Set up environment variables (example) export ALLOWED_COMMANDS=git,ls,mkdir,python

   Optionally configure integration with Claude Desktop or other MCP clients

6. Verify the MCP configuration by connecting through an MCP client and issuing an execute_command request with an allowed command.

Tips and notes:

• The server uses an allowlist approach for security. Update ALLOWED_COMMANDS to enable/disable commands as needed.
• Commands are validated by prefix and run without invoking a shell to reduce injection risk.
• Output is streamed in real time, but failed commands return structured error messages for easier debugging.
• For Claude Desktop integration, place the generated mcpServers configuration in the Claude config path (MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%/Claude/claude_desktop_config.json).
• If you modify the allowed commands or security settings, restart the MCP server to ensure changes take effect.
• When debugging, use the MCP Inspector to monitor requests and responses and surface logs in the browser.