MCP Script Runner

A Model Context Protocol (MCP) server that provides coding agents with a generic interface to execute developer-defined bash scripts within a Dockerized environment.

# Clone and run with Docker git clone <repository-url> cd devmcp docker compose up --build -d # Check logs docker compose logs -f

# Clone repository git clone <repository-url> cd devmcp # Install dependencies pip install -r requirements.txt # Run the server python -m mcp_script_runner.server

The MCP Script Runner Server enables AI agents to:

- Execute predefined bash scriptswith configurable arguments
- Manage working directoriesfor different project contexts
- Get script informationincluding descriptions and available arguments
- List available scriptsdynamically
- Handle script timeoutsand error conditions gracefully

The project includes full Docker support for containerized execution:

- 🔧 Ready-to-use containerswith all dependencies
- 🛡️ Isolated execution environment
- 📦 Easy deploymentwith Docker Compose
- 🔍 Debug capabilitieswith interactive shell access

SeeDOCKER.mdfor complete Docker usage guide.

# Start the MCP server docker compose up --build -d # Interactive development shell docker compose --profile debug up shell # Test script execution docker compose exec mcp-script-runner bash scripts/hello.sh

# Install Python dependencies pip install -r requirements.txt # Verify installation python -c "from src.mcp_script_runner.server import main; print('✅ Installation OK')"

# Build container docker build -t mcp-script-runner . # Or use Docker Compose docker compose up --build

{ "working_directory": ".", "scripts": { "hello": { "path": "scripts/hello.sh", "description": "Simple hello world script", "arguments": [], "timeout": 30 }, "list_files": { "path": "scripts/list_files.sh", "description": "List files in directory with options", "arguments": ["directory", "options"], "timeout": 10 } } }

project/ ├── .mcp-config.json ├── scripts/ │ ├── hello.sh │ ├── list_files.sh │ └── system_info.sh └── src/ └── mcp_script_runner/

{ "tool": "run_script", "arguments": { "script_name": "hello", "arguments": [] } }

# Start MCP server (listens on stdio) python -m mcp_script_runner.server # Or with explicit path PYTHONPATH=src python -m mcp_script_runner.server

# Background service docker compose up -d # Interactive mode docker compose run --rm mcp-script-runner # Debug shell docker compose --profile debug up shell

#!/bin/bash echo "Hello from MCP Script Runner!" echo "Current directory: $(pwd)" echo "Script arguments: $@" echo "Date: $(date)"

File Listing Script (scripts/list_files.sh)

#!/bin/bash DIRECTORY=${1:-.} OPTIONS=${2:-"-la"} echo "Listing files in: $DIRECTORY" ls $OPTIONS "$DIRECTORY"

System Info Script (scripts/system_info.sh)

#!/bin/bash echo "=== System Information ===" echo "OS: $(uname -s)" echo "Kernel: $(uname -r)" echo "Architecture: $(uname -m)" echo "Uptime: $(uptime)" echo "Disk Usage:" df -h

# Run tests locally python -m pytest tests/ # Run tests in Docker docker compose run --rm mcp-script-runner python -m pytest tests/

# Test script execution python -c " import asyncio from src.mcp_script_runner.executor import ScriptExecutor from src.mcp_script_runner.config import ConfigManager async def test(): cm = ConfigManager() ex = ScriptExecutor(cm) result = await ex.execute_script('hello') print(f'Exit code: {result.exit_code}') print(result.stdout) asyncio.run(test()) "

- 🛡️ Containerized executionisolates script execution
- 👤 Non-root userinside containers (mcpuser)
- 📁 Limited file accessthrough volume mounts
- ⏱️ Script timeoutsprevent runaway processes
- 🚫 No shell injection- arguments passed safely

- Build and test commands
- Code generation scripts
- Development environment setup

- System monitoring scripts
- Backup and maintenance tasks
- Configuration management

- Deployment scripts
- Environment validation
- Automated testing workflows

- Task automation
- Report generation
- Resource management

# Check Python path export PYTHONPATH=src # Verify dependencies pip install -r requirements.txt # Check configuration python -c "from src.mcp_script_runner.config import ConfigManager; cm = ConfigManager(); print('Config OK')"

# Check script permissions chmod +x scripts/*.sh # Test script directly bash scripts/hello.sh # Check Docker logs docker compose logs mcp-script-runner

# Rebuild container docker compose up --build # Check container status docker compose ps # Interactive debugging docker compose run --rm mcp-script-runner bash

# Local debug PYTHONPATH=src python -c " import logging logging.basicConfig(level=logging.DEBUG) from mcp_script_runner.server import main import asyncio asyncio.run(main()) " # Docker debug docker compose --profile debug up shell

devmcp/ ├── 📄 README.md # This file ├── 🐳 DOCKER.md # Docker usage guide ├── 📋 TASKS.md # Development tasks ├── ⚙️ .mcp-config.json # Configuration ├── 🐳 Dockerfile # Container definition ├── 🐳 docker-compose.yml # Container orchestration ├── 📦 requirements.txt # Python dependencies ├── 📦 pyproject.toml # Python project config ├── 🔧 scripts/ # Example scripts ├── 🐍 src/mcp_script_runner/ # Python source code └── 🧪 tests/ # Unit tests

- Create script inscripts/directory
- Make executable:chmod +x scripts/myscript.sh
- Add to.mcp-config.json:

{ "scripts": { "myscript": { "path": "scripts/myscript.sh", "description": "My custom script", "arguments": ["arg1", "arg2"], "timeout": 30 } } }

- Reload configuration: Usereload_configtool
- Fork the repository
- Create feature branch
- Add tests for new functionality
- Test with Docker:docker compose up --build
- Submit pull request

# Using Docker Compose docker compose up -d # Using Docker Swarm docker stack deploy -c docker-compose.yml mcp-stack # Using Kubernetes kubectl apply -f k8s/

{ "mcpServers": { "script-runner": { "command": "docker", "args": ["compose", "-f", "/path/to/devmcp/docker-compose.yml", "run", "--rm", "mcp-script-runner"] } } }

MIT License - see LICENSE file for details.

- 📖 Documentation: SeeDOCKER.mdfor Docker usage
- 🐛 Issues: Create GitHub issue
- 💬 Discussions: GitHub Discussions
- 📧 Contact: See repository contributors

Manage Docker containers, volumes, and services using natural language commands.