mcp_command_server

The MCP Command Server provides a secure, JSON-RPC 2.0 API for remotely executing shell commands on a host. It is designed with a strong security model that filters commands using a defined exclusion pattern to prevent harmful operations, while remaining fully containerized for easy deployment. The server ships with built-in API documentation accessible via the /context endpoint, and it runs in a containerized (Docker) setup for production-ready deployments. You can interact with the API by sending JSON-RPC requests to the server’s POST endpoint, for example to execute a safe command and receive stdout or error details.

Key capabilities include a command execution endpoint (command/get) that accepts a command string, a self-documenting /context endpoint that provides markdown API docs, and a robust security layer that blocks dangerous patterns via an exclude.yaml configuration. The API design aligns with JSON-RPC 2.0 and includes detailed error codes for missing parameters and execution failures, making it suitable for integration into automated tooling, CI pipelines, or remote administration workflows.

Prerequisites

• Docker and Docker Compose installed on the target host
• Git (optional, for cloning the repository)

Using Docker (recommended)

1. Pull the prebuilt container image (or build locally if you have access to the Dockerfile): docker pull copyleftdev/mcp_command_server

2. Run the container (ports mapped if you need to expose externally): docker run -d --name mcp_command_server -p 3030:3030 copyleftdev/mcp_command_server

3. Verify the server is running: curl http://localhost:3030/context

Building from source (Rust) if you prefer to compile yourself

1. Ensure Rust toolchain is installed (1.74+ recommended): curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

2. Clone the repository and build: git clone https://github.com/yourusername/mcp_command_server.git cd mcp_command_server cargo build --release

3. Run the server binary: ./target/release/mcp_command_server

Note: If you build from source, you may want to configure command exclusion patterns via exclude.yaml and expose the /context documentation endpoint as configured in the project.

Environment variables and configuration options:

• The server uses exclude.yaml to block potentially dangerous commands. Review and customize this file to fit your security requirements.
• The /context endpoint serves the API documentation in markdown; use it to understand available methods, request formats, and error codes.
• When deploying with Docker, ensure proper network and port exposure (default port is 3030).
• For production, run as a non-root user inside the container if your image supports it, and consider mounting a persistent volume for logs or configuration.
• If you encounter JSON-RPC errors, verify the command parameter is correctly escaped and that the command is allowed by the exclusion rules.