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:
-
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
-
Command Validation
- Command prefix validation prevents command injection
- No shell execution for improved security
- Environment variables are properly sanitized
-
Error Handling
- Comprehensive error handling for unauthorized commands
- Clear error messages for debugging
- Failed commands don't crash the server
-
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:
-
Unauthorized Commands
{ "code": "InvalidParams", "message": "Command not allowed: [command]. Allowed commands: git, ls, mkdir, cd, npm, npx, python" } -
Execution Failures
{ "content": [ { "type": "text", "text": "Command execution failed: [error message]" } ], "isError": true }
🤝 Contributing
- Fork the repository
- Create your feature branch
- Commit your changes
- Push to the branch
- Create a new Pull Request
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.