command-executor MCP Server

A Model Context Protocol server for executing pre-approved commands securely.

🎥 Demo

https://github.com/user-attachments/assets/ed763a12-b685-4e0b-b9a5-bc948a590f51

✨ Features

• Secure command execution with pre-approved command list

• Configurable allowed commands through environment variables

• Built with TypeScript and MCP SDK

• Communication via stdio for seamless integration

• Error handling and security validations

• Real-time command output streaming

🚀 Installation

Install dependencies:

Build the server:

For development with auto-rebuild:

⚙️ Configuration

🔒 Allowed Commands

By default, the following commands are allowed:

• git

• ls

• mkdir

• cd

• npm

• npx

• python

You can customize the allowed commands by setting the ALLOWED_COMMANDS environment variable:

🔌 Claude Desktop Integration

To use with Claude Desktop, add the server config:

On MacOS:

On Windows:

Configuration example:

🛡️ Security Considerations

The command-executor server implements several security measures:

1. Pre-approved Command List

   • Only explicitly allowed commands can be executed

   • Default list is restrictive and security-focused

   • Commands are validated by prefix to prevent injection

2. Command Validation

   • Command prefix validation prevents command injection

   • No shell execution for improved security

   • Environment variables are properly sanitized

3. Error Handling

   • Comprehensive error handling for unauthorized commands

   • Clear error messages for debugging

   • Failed commands don't crash the server

4. Environment Isolation

   • Server runs in its own environment

   • Environment variables can be controlled

   • Limited system access

💻 Development

📁 Project Structure

🐛 Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector:

The Inspector will provide a URL to access debugging tools in your browser.

🛠️ Tool API

The server provides a single tool:

execute_command

Executes a pre-approved command.

Parameters:

• command (string, required): The command to execute

Example Request:

Example Response:

Error Response:

❌ Error Handling

The server provides detailed error messages for various scenarios:

1. Unauthorized Commands

   { "code": "InvalidParams", "message": "Command not allowed: [command]. Allowed commands: git, ls, mkdir, cd, npm, npx, python" }

2. Execution Failures

   { "content": [ { "type": "text", "text": "Command execution failed: [error message]" } ], "isError": true }

🤝 Contributing

1. Fork the repository

2. Create your feature branch

3. Commit your changes

4. Push to the branch

5. Create a new Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.