joshwlewis/mcp-shell

MCP Shell Server

An MCP (Model Context Protocol) server that executes bash scripts and commands, returning the stdout and stderr output. This server implements HTTP streaming transport for real-time communication.

Features

• Execute bash scripts and commands
• Return both stdout and stderr output
• HTTP streaming transport support
• Secure script execution with temporary files
• Comprehensive error handling

Installation

1. Clone this repository
2. Install dependencies:

   go mod tidy
   

Usage

Starting the Server

The server can be started with HTTP streaming transport:

go run main.go -http :8080

Or without the -http flag to use stdio transport:

go run main.go

Available Tools

The server provides one tool:

• execute_shell: Executes a bash script or command and returns the output

Tool Parameters

• script (string, required): The bash script or command to execute

Example Usage

The server will be available at http://localhost:8080 when using HTTP transport. You can send MCP requests to execute shell commands.

Example request structure:

{
  "name": "execute_shell",
  "arguments": {
    "script": "echo 'Hello World' && ls -la"
  }
}

Example response:

{
  "content": [
    {
      "type": "text",
      "text": "Script executed successfully!\n\nSTDOUT:\nHello World\ntotal 8\ndrwxr-xr-x  2 user  staff   64 Dec 20 10:00 .\ndrwxr-xr-x  3 user  staff   96 Dec 20 10:00 ..\n-rw-r--r--  1 user  staff  123 Dec 20 10:00 main.go\n-rw-r--r--  1 user  staff   45 Dec 20 10:00 go.mod\n\nSTDERR:\n"
    }
  ]
}

Security Considerations

• Scripts are executed in temporary files that are automatically cleaned up
• The server runs with the same permissions as the user running it
• Consider running this server in a controlled environment
• Docker container runs as non-root user for enhanced security

Troubleshooting

Docker Issues

Port Already in Use:

# Check what's using port 8080
lsof -i :8080

# Stop existing container
./docker-build.sh stop

# Or use a different port
docker run -d -p 8081:8080 --name mcp-shell-container mcp-shell

Build Failures:

# Clean build without cache
docker build --no-cache -t mcp-shell .

# Check Docker daemon is running
docker info

Container Won't Start:

# Check container logs
./docker-build.sh logs

# Check container status
./docker-build.sh status

# Restart container
./docker-build.sh restart

Permission Issues:

# Make script executable
chmod +x docker-build.sh

# Run with sudo if needed
sudo docker build -t mcp-shell .

Common Commands

# List running containers
docker ps

# List all containers
docker ps -a

# Remove all stopped containers
docker container prune

# Remove unused images
docker image prune

Building

Local Build

To build the server locally:

go build -o mcp-shell main.go

Docker Build

To build and run the server using Docker:

# Build the Docker image
docker build -t mcp-shell .

# Run the container
docker run -d -p 8080:8080 --name mcp-shell-container mcp-shell

# Or use the provided script
./docker-build.sh run

Docker Build Details

The Dockerfile uses a multi-stage build process:

1. Build Stage: Uses golang:1.23-alpine to compile the Go binary
2. Runtime Stage: Uses ubuntu:24.04 as the lightweight runtime environment
3. Security: Runs as non-root user for enhanced security
4. Optimization: Only copies necessary files (go.mod, go.sum, main.go)

Prerequisites

• Docker installed and running
• Docker Compose (optional, for easier management)

Build Options

Quick Build:

docker build -t mcp-shell .

Build with Custom Tag:

docker build -t mcp-shell:latest .
docker build -t mcp-shell:v1.0.0 .

Build with No Cache (for clean rebuild):

docker build --no-cache -t mcp-shell .

Docker Compose

To run with Docker Compose:

# Build and start the service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down

Docker Compose Features

• Automatic restart: Container restarts unless manually stopped
• Health checks: Built-in health monitoring
• Network isolation: Dedicated network for the service
• Port mapping: Exposes port 8080 for HTTP access

Compose Commands

# Start in background
docker-compose up -d

# Start with logs
docker-compose up

# Rebuild and start
docker-compose up --build

# View logs
docker-compose logs -f mcp-shell

# Stop services
docker-compose down

# Stop and remove volumes
docker-compose down -v

Docker Script Commands

The docker-build.sh script provides convenient commands for managing the Docker container:

./docker-build.sh build    # Build the image
./docker-build.sh run      # Build and run the server
./docker-build.sh start    # Start existing container
./docker-build.sh stop     # Stop and remove container
./docker-build.sh restart  # Restart the container
./docker-build.sh logs     # View container logs
./docker-build.sh status   # Show container status
./docker-build.sh clean    # Clean up Docker resources

Script Usage Examples

# First time setup - build and run
./docker-build.sh run

# Check if container is running
./docker-build.sh status

# View server logs
./docker-build.sh logs

# Restart the server
./docker-build.sh restart

# Clean up everything
./docker-build.sh clean

Container Management

The script automatically handles:

• Container naming: Uses mcp-shell-container
• Port mapping: Maps host port 8080 to container port 8080
• Restart policy: Container restarts unless manually stopped
• Resource cleanup: Proper removal of containers and images

License

This project is licensed under the MIT License.