54rt1n_container_mcp

by 54rt1n

A secure, container-based MCP server for executing tools like bash commands, Python code, file operations, and web scraping on behalf of large language models.

Secure Containerized MCP Server for AI Tools

Overview

Container-MCP provides a sandboxed environment for safely executing code, running commands, accessing files, and performing web operations requested by large language models. It implements the MCP protocol to expose these capabilities as tools that can be discovered and called by AI systems in a secure manner.

The architecture uses a domain-specific manager pattern with multi-layered security to ensure tools execute in isolated environments with appropriate restrictions, protecting the host system from potentially harmful operations.

Key Features

Multi-layered Security
Container isolation using Podman/Docker
AppArmor profiles for restricting access
Firejail sandboxing for additional isolation
Resource limits (CPU, memory, execution time)
Path traversal prevention
Allowed extension restrictions
MCP Protocol Implementation
Standardized tool discovery and execution
Resource management
Async execution support
Domain-Specific Managers
BashManager: Secure command execution
PythonManager: Sandboxed Python code execution
FileManager: Safe file operations
WebManager: Secure web browsing and scraping
Configurable Environment
Extensive configuration via environment variables
Custom environment support
Development and production modes

Available Tools

System Operations

`system_run_command`

Executes bash commands in a secure sandbox environment.

{
  "stdout": "file1.txt\nfile2.txt\n",
  "stderr": "",
  "exit_code": 0,
  "success": true
}

`system_run_python`

Executes Python code in a secure sandbox environment.

{
  "output": "Hello, world!\n",
  "error": "",
  "result": 42,
  "success": true
}

`system_env_var`

Gets environment variable values.

{
  "variables": {
    "MCP_PORT": "8000",
    "SANDBOX_ROOT": "/app/sandbox"
  },
  "requested_var": "8000"
}

File Operations

`file_read`

Reads file contents safely.

{
  "content": "This is the content of the file.",
  "size": 31,
  "modified": 1673452800.0,
  "success": true
}

`file_write`

Writes content to a file safely.

{
  "success": true,
  "path": "data/myfile.txt"
}

`file_list`

Lists contents of a directory safely.

{
  "entries": [
    {
      "name": "file1.txt",
      "path": "file1.txt",
      "is_directory": false,
      "size": 1024,
      "modified": 1673452800.0
    },
    {
      "name": "data",
      "path": "data",
      "is_directory": true,
      "size": null,
      "modified": 1673452500.0
    }
  ],
  "path": "/",
  "success": true
}

`file_delete`

Deletes a file safely.

{
  "success": true,
  "path": "temp/old_file.txt"
}

`file_move`

Moves or renames a file safely.

{
  "success": true,
  "source": "data/old_name.txt",
  "destination": "data/new_name.txt"
}

Web Operations

`web_search`

Uses a search engine to find information on the web.

{
  "results": [
    {
      "title": "Search Result Title",
      "url": "https://example.com/page1",
      "snippet": "Text snippet from the search result..."
    }
  ],
  "query": "example search query"
}

`web_scrape`

Scrapes a specific URL and returns the content.

{
  "content": "This is the content of the web page...",
  "url": "https://example.com/page",
  "title": "Example Page",
  "success": true,
  "error": null
}

`web_browse`

Interactively browses a website using Playwright.

{
  "content": "<!DOCTYPE html><html>...</html>",
  "url": "https://example.com/after_redirect",
  "title": "Example Page",
  "success": true,
  "error": null
}

Execution Environment

Container Environment

The main Container-MCP service runs inside a container (using Podman or Docker) providing the first layer of isolation:

Base Image: Ubuntu 24.04
User: Non-root ubuntu user
Python: 3.12
Network: Limited to localhost binding only
Filesystem: Volume mounts for configuration, data, and logs
Security: AppArmor, Seccomp, and capability restrictions

Bash Execution Environment

The Bash execution environment is configured with multiple isolation layers:

Allowed Commands: Restricted to safe commands configured in BASH_ALLOWED_COMMANDS
Firejail Sandbox: Process isolation with restricted filesystem access
AppArmor Profile: Fine-grained access control
Resource Limits:
Execution timeout (default: 30s, max: 120s)
Limited directory access to sandbox only
Network: No network access
File System: Read-only access to data, read-write to sandbox

Python Execution Environment

The Python execution environment is designed for secure code execution:

Python Version: 3.12
Memory Limit: Configurable memory ceiling (default: 256MB)
Execution Timeout: Configurable time limit (default: 30s, max: 120s)
AppArmor Profile: Restricts access to system resources
Firejail Sandbox: Process isolation
Capabilities: All capabilities dropped
Network: No network access
Available Libraries: Only standard library
Output Capturing: stdout/stderr redirected and sanitized
Resource Controls: CPU and memory limits enforced

File System Environment

The file system environment controls access to files within the sandbox:

Base Directory: All operations restricted to sandbox root
Path Validation: All paths normalized and checked for traversal attempts
Size Limits: Maximum file size enforced (default: 10MB)
Extension Control: Only allowed extensions permitted (default: txt, md, csv, json, py)
Permission Control: Appropriate read/write permissions enforced
Isolation: No access to host file system

Web Environment

The web environment provides controlled access to external resources:

Domain Control: Optional whitelisting of allowed domains
Timeout Control: Configurable timeouts for operations
Browser Control: Headless browser via Playwright for full rendering
Scraping Control: Simple scraping via requests/BeautifulSoup
Content Sanitization: All content parsed and sanitized
Network Isolation: Separate network namespace via container

Architecture

The project follows a modular architecture:

container-mcp/
├── cmcp/                     # Main application code
│   ├── managers/             # Domain-specific managers
│   │   ├── bash_manager.py   # Secure bash execution
│   │   ├── python_manager.py # Secure python execution
│   │   ├── file_manager.py   # Secure file operations
│   │   └── web_manager.py    # Secure web operations
│   ├── utils/                # Utility functions
│   ├── config.py             # Configuration system
│   └── main.py               # MCP server setup
├── apparmor/                 # AppArmor profiles
├── config/                   # Configuration files
├── bin/                      # Build/run scripts
├── data/                     # Data directory
├── logs/                     # Log directory
├── sandbox/                  # Sandboxed execution space
│   ├── bash/                 # Bash sandbox
│   ├── python/               # Python sandbox
│   ├── files/                # File operation sandbox
│   └── browser/              # Web browser sandbox
├── temp/                     # Temporary storage
└── tests/                    # Test suites

Each manager follows consistent design patterns:

.from_env() class method for environment-based initialization
Async execution methods for non-blocking operations
Strong input validation and error handling
Security-first approach to all operations

Security Measures

Container-MCP implements multiple layers of security:

Container Isolation: Uses Podman/Docker for container isolation
AppArmor Profiles: Fine-grained access control for bash and Python execution
Firejail Sandboxing: Additional process isolation
Resource Limits: Memory, CPU, and execution time limits
Path Traversal Prevention: Validates and normalizes all file paths
Allowed Extension Restrictions: Controls what file types can be accessed
Network Restrictions: Controls what domains can be accessed
Least Privilege: Components run with minimal necessary permissions

Installation

Prerequisites

Linux system with Podman or Docker
Python 3.12+
Firejail (apt install firejail or dnf install firejail)
AppArmor (apt install apparmor apparmor-utils or dnf install apparmor apparmor-utils)

Quick Start

The quickest way to get started is to use the all-in-one script:

git clone https://github.com/container-mcp/container-mcp.git
cd container-mcp
chmod +x bin/00-all-in-one.sh
./bin/00-all-in-one.sh

Step-by-Step Installation

You can also perform the installation steps individually:

Initialize the project:

shell ./bin/01-init.sh

Build the container:

shell ./bin/02-build-container.sh

Set up the environment:

shell ./bin/03-setup-environment.sh

Run the container:

shell ./bin/04-run-container.sh

Run tests (optional):

shell ./bin/05-run-tests.sh

Usage

Once the container is running, you can connect to it using any MCP client implementation. The server will be available at http://localhost:8000 or the port specified in your configuration.

Important: When configuring your MCP client, you must set the endpoint URL to http://127.0.0.1:<port>/sse (where <port> is 8000 by default or the port you've configured). The /sse path is required for proper server-sent events communication.

Example Python Client

from mcp.client.sse import sse_client
from mcp import ClientSession
import asyncio

async def main():
    # Connect to the Container-MCP server
    # Note the /sse endpoint suffix required for SSE communication
    sse_url = "http://127.0.0.1:8000/sse"  # Or your configured port

    # Connect to the SSE endpoint
    async with sse_client(sse_url) as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize the connection
            await session.initialize()

            # Discover available tools
            result = await session.list_tools()
            print(f"Available tools: {[tool.name for tool in result.tools]}")

            # Execute a Python script
            python_result = await session.execute_tool(
                "system_run_python",
                {"code": "print('Hello, world!')\nresult = 42\n_ = result"}
            )
            print(f"Python result: {python_result}")

            # Execute a bash command
            bash_result = await session.execute_tool(
                "system_run_command",
                {"command": "ls -la"}
            )
            print(f"Command output: {bash_result['stdout']}")

if __name__ == "__main__":
    asyncio.run(main())

Configuration

Container-MCP can be configured through environment variables, which can be set in volume/config/custom.env:

Server Configuration

# MCP Server Configuration
MCP_HOST=127.0.0.1
MCP_PORT=9001
DEBUG=true
LOG_LEVEL=INFO

Bash Manager Configuration

# Bash Manager Configuration
BASH_ALLOWED_COMMANDS=ls,cat,grep,find,echo,pwd,mkdir,touch
BASH_TIMEOUT_DEFAULT=30
BASH_TIMEOUT_MAX=120

Python Manager Configuration

# Python Manager Configuration
PYTHON_MEMORY_LIMIT=256
PYTHON_TIMEOUT_DEFAULT=30
PYTHON_TIMEOUT_MAX=120

File Manager Configuration

# File Manager Configuration 
FILE_MAX_SIZE_MB=10
FILE_ALLOWED_EXTENSIONS=txt,md,csv,json,py

Web Manager Configuration

# Web Manager Configuration
WEB_TIMEOUT_DEFAULT=30
WEB_ALLOWED_DOMAINS=*

Development

Setting Up a Development Environment

Create a Python virtual environment:

shell python3.12 -m venv .venv source .venv/bin/activate

Install dependencies:

shell pip install -r requirements-dev.txt

Install the package in development mode:

shell pip install -e .

Running Tests

# Run all tests
pytest

# Run only unit tests
pytest tests/unit

# Run only integration tests
pytest tests/integration

# Run with coverage report
pytest --cov=cmcp --cov-report=term --cov-report=html

Development Server

To run the MCP server in development mode:

python -m cmcp.main --test-mode

License

This project is licensed under the Apache License 2.0.

Author

Martin Bukowski

About

A podman ubuntu 24.04 container that serves a MCP server; with file, code execution, bash shell, and more.

No releases published

Packages 0

No packages published

Languages

Features & Capabilities

Implementation Details

View on GitHub

Stats

0 Views

0 Likes

4 GitHub Stars

Repository Info

54rt1n Organization

Similar Servers

continuedev_continue by continuedev

cherryhq_cherry_studio by CherryHQ

bytedance_ui_tars_desktop by bytedance

No result found

Advanced Search

Search Preferences

54rt1n_container_mcp

Secure Containerized MCP Server for AI Tools

Overview

Key Features

Available Tools

System Operations

system_run_command

system_run_python

system_env_var

File Operations

file_read

file_write

file_list

file_delete

file_move

Web Operations

web_search

web_scrape

web_browse

Execution Environment

Container Environment

Bash Execution Environment

Python Execution Environment

File System Environment

Web Environment

Architecture

Security Measures

Installation

Prerequisites

Quick Start

Step-by-Step Installation

Usage

Example Python Client

Configuration

Server Configuration

Bash Manager Configuration

Python Manager Configuration

File Manager Configuration

Web Manager Configuration

Development

Setting Up a Development Environment

Running Tests

Development Server

License

Author

About

Resources

License

Stars

Watchers

Forks

Languages

Features & Capabilities

Implementation Details

Stats

Repository Info

Similar Servers

Drop files here or click to upload.

Drop files here or click to upload.

`system_run_command`

`system_run_python`

`system_env_var`

`file_read`

`file_write`

`file_list`

`file_delete`

`file_move`

`web_search`

`web_scrape`

`web_browse`