https://github.com/cnosuke/mcp-command-exec
https://github.com/cnosuke/mcp-command-exec
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/cnosuke/mcp-command-exec
- Owner: cnosuke
- Created: 2025-03-26T09:13:56.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-04-06T00:16:59.000Z (6 months ago)
- Last Synced: 2025-04-06T01:19:32.365Z (6 months ago)
- Language: Go
- Size: 42 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-mcp-servers - **mcp-command-exec** - Go-based `go` `go install cnosuke/mcp-command-exec@latest` (DevOps)
- awesome-mcp-servers - **mcp-command-exec** - Go-based `go` `go install cnosuke/mcp-command-exec@latest` (DevOps)
README
# MCP Command Executor
MCP Command Executor is a server implementation that allows safe execution of system commands via the MCP protocol. This server ensures security by only executing commands that are registered in an allowlist.
## Features
- Command execution via MCP protocol
- Command filtering using an allowlist
- Customizable allowed commands via environment variables
- Environment variable support for command execution
- Global environment variables in configuration file
- Per-command environment variables
- Command execution result as text output
## Requirements
- Go 1.24 or later
- github.com/metoro-io/mcp-golang
- Other dependencies listed in [go.mod](go.mod)
## Installation
```bash
go install github.com/cnosuke/mcp-command-exec
```
Or clone the repository and build manually:
```bash
git clone https://github.com/cnosuke/mcp-command-exec.git
cd mcp-command-exec
make build
```
## Configuration
The server is configured via a YAML file (default: config.yml). For example:
```yaml
# Logging configuration
log: 'log/mcp-command-exec.log'
debug: false
command_exec:
allowed_commands:
- git
- ls
- mkdir
- cd
- npm
- npx
- python
# Working directory settings
default_working_dir: '/home/user'
allowed_dirs:
- '/home/user/projects'
- '/tmp'
# Path search settings
search_paths:
- '/usr/local/bin'
- '/usr/bin'
path_behavior: 'prepend' # prepend, replace, append
# Global environment variables
environment:
HOME: '/home/user'
GOPATH: '/home/user/go'
GOMODCACHE: '/home/user/go/pkg/mod'
LANG: 'en_US.UTF-8'
```
You can override configurations using environment variables:
- `LOG_PATH`: Path to log file
- `DEBUG`: Enable debug mode (true/false)
- `ALLOWED_COMMANDS`: Comma-separated list of allowed commands (overrides configuration file)
Example:
```bash
ALLOWED_COMMANDS=git,ls,cat,echo mcp-command-exec server
```
## Logging
Logging behavior is controlled through configuration:
- If `log` is set in the config file, logs will be written to the specified file
- If `log` is empty, no logs will be produced
- Set `debug: true` for more verbose logging
## Command-Line Parameters
When starting the server, you can specify various settings:
```
./bin/mcp-command-exec server [options]
```
Options:
- `--config`, `-c`: Path to the configuration file (default: "config.yml").
## MCP Tool Specification
### command_exec
Executes a system command.
**Parameters**:
- `command`: The command to execute (string)
- `working_dir`: Optional working directory for command execution
- `env`: Optional environment variables for this command execution (object)
- Takes precedence over environment variables in the configuration file
- Example: `{"DEBUG": "1", "LANG": "en_US.UTF-8"}`
**Response**:
- Success: Command execution result (stdout/stderr)
- Failure: Error message
Example (JSON request):
```json
{
"method": "tool",
"id": "1",
"params": {
"name": "command_exec",
"input": {
"command": "ls -la",
"working_dir": "/home/user/project",
"env": {
"DEBUG": "1",
"LANG": "en_US.UTF-8"
}
}
}
}
```
## Security
This server ensures security through the following methods:
1. Only executes commands included in the allowlist
2. Executes commands directly without using a shell, preventing shell injection
3. Validates commands by prefix (e.g., `ls` is allowed but `ls;rm -rf` is rejected)
4. Safe handling and override control of environment variables
5. Strict error handling
## Development
### Building
```bash
make build
```
### Testing
```bash
make test
```
### Running
```bash
make run
```
## Using with Claude Desktop
To integrate with Claude Desktop, add an entry to your `claude_desktop_config.json` file:
```json
{
"mcpServers": {
"command": {
"command": "./bin/mcp-command-exec",
"args": ["server"],
"env": {
"LOG_PATH": "mcp-command-exec.log",
"DEBUG": "false",
"ALLOWED_COMMANDS": "git,ls,cat,echo,find"
}
}
}
}
```
## Acknowledgements
This project was inspired by [command-executor-mcp-server](https://github.com/Sunwood-ai-labs/command-executor-mcp-server) by Sunwood AI Labs. We extend our gratitude for their pioneering work in MCP server implementations for command execution.
## License
MIT
Author: cnosuke ( x.com/cnosuke )