Command Executor MCP Server

<div align="center"> # command-executor MCP Server <img src="https://raw.githubusercontent.com/Sunwood-ai-labs/command-executor-mcp-server/refs/heads/master/assets/header.svg" alt="Command Executor MCP Server"/> <a href="README.md"><img src="https://img.shields.io/badge/english-document-white.svg" alt="EN doc"></a> <a href="README.ja.md"><img src="https://img.shields.io/badge/ドキュメント-日本語-white.svg" alt="JA doc"/></a> </div> 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: ```bash npm install ``` Build the server: ```bash npm run build ``` For development with auto-rebuild: ```bash 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: ```bash export ALLOWED_COMMANDS=git,ls,mkdir,python ``` ### 🔌 Claude Desktop Integration To use with Claude Desktop, add the server config: On MacOS: ```bash ~/Library/Application Support/Claude/claude_desktop_config.json ``` On Windows: ``` %APPDATA%/Claude/claude_desktop_config.json ``` Configuration example: ```json { "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](https://github.com/modelcontextprotocol/inspector): ```bash 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: ```json { "name": "execute_command", "arguments": { "command": "git status" } } ``` Example Response: ```json { "content": [ { "type": "text", "text": "On branch main\nNothing to commit, working tree clean" } ] } ``` Error Response: ```json { "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 ```json { "code": "InvalidParams", "message": "Command not allowed: [command]. Allowed commands: git, ls, mkdir, cd, npm, npx, python" } ``` 2. Execution Failures ```json { "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.