command executor mcp server

# 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
2. Only explicitly allowed commands can be executed
3. Default list is restrictive and security-focused

4. Commands are validated by prefix to prevent injection

5. Command Validation

6. Command prefix validation prevents command injection
7. No shell execution for improved security

8. Environment variables are properly sanitized

9. Error Handling

10. Comprehensive error handling for unauthorized commands
11. Clear error messages for debugging

12. Failed commands do not crash the server

13. Environment Isolation

14. Server runs in its own environment
15. Environment variables can be controlled
16. 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
Nothing 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.