What is Command Executor Mcp Server

The command-executor-mcp-server is a Model Context Protocol server designed for securely executing pre-approved commands. It ensures that only specified commands can be executed, enhancing security and control.

Use cases

Use cases for the command-executor-mcp-server include executing commands in a controlled environment for development, integrating with applications that require command execution, and enhancing security in automated workflows by limiting command execution to a predefined list.

How to use

To use the command-executor-mcp-server, install the dependencies using ‘npm install’, build the server with ‘npm run build’, and configure allowed commands through environment variables. Integrate with Claude Desktop by adding the server configuration to the appropriate JSON file.

Key features

Key features include secure command execution with a pre-approved command list, configurable allowed commands via environment variables, TypeScript and MCP SDK support, seamless stdio communication, robust error handling, and real-time command output streaming.

Where to use

undefined

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:

npm install

Build the server:

npm run build

For development with auto-rebuild:

npm run watch

⚙️ 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:

export ALLOWED_COMMANDS=git,ls,mkdir,python

🔌 Claude Desktop Integration

To use with Claude Desktop, add the server config:

On MacOS:

~/Library/Application Support/Claude/claude_desktop_config.json

On Windows:

%APPDATA%/Claude/claude_desktop_config.json

Configuration example:

{
  "mcpServers": {
    "command-executor": {
      "command": "/path/to/command-executor/build/index.js"
    }
  }
}

🛡️ 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

command-executor/
├─ src/
│  └─ index.ts      # Main server implementation
├─ build/
│  └─ index.js      # Compiled JavaScript
├─ assets/
│  └─ header.svg    # Project header image
└─ package.json     # Project configuration

🐛 Debugging

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

npm run 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:

{
  "name": "execute_command",
  "arguments": {
    "command": "git status"
  }
}

Example Response:

{
  "content": [
    {
      "type": "text",
      "text": "On branch main\nNothing to commit, working tree clean"
    }
  ]
}

Error Response:

{
  "content": [
    {
      "type": "text",
      "text": "Command execution failed: Command not allowed"
    }
  ],
  "isError": true
}

❌ 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.