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.