MCP Terminal

A Model Context Protocol (MCP) server that provides containerized terminal environments with dynamic context management and MCP server forwarding.

Description

MCP Terminal creates isolated container environments for different contexts (projects, experiments, etc.) and provides seamless command execution, file management, and access to container-based MCP servers. Each context gets its own container with persistent storage, environment variables, and custom tooling.

Features

• Multi-Platform Container Support: Works with Docker, Podman, and Kubernetes
• Dynamic Contexts: Create isolated environments on-demand using any string as context name
• MCP Server Forwarding: Automatically discover and forward MCP servers running inside containers
• Persistent Storage: Each context maintains persistent volumes for data retention
• Built-in Tools: Execute commands, manage container lifecycle, view logs
• Environment Variable Expansion: Support for ${VAR} and $VAR syntax in mount paths
• Graceful Shutdown: Automatic container cleanup on server termination

Built-in Tools

• execute - Run commands in container environments
• start - Start container for a context
• stop - Stop container for a context
• logs - Retrieve container logs

Dynamic Tools

Additional tools are automatically discovered from MCP servers running inside containers, such as:

• File system operations (read, write, list files)
• Git operations (status, log, add)
• System information (disk usage, processes)
• Custom tools from your container images

How to Run

Prerequisites

• Rust 1.75+
• Docker 20.10+ OR Podman 3.0+
• For Kubernetes: kubectl access to cluster

Docker

1. Build and run:

   cargo build --release
   ./target/release/mcp-terminal
   

2. Test the server:

   curl http://localhost:3002/discovery
   

3. Create a context:

   curl http://localhost:3002/my-project/discovery
   

Podman

# Ensure Podman socket is running
systemctl --user enable --now podman.socket

# Run the server (auto-detects Podman)
./target/release/mcp-terminal

Kubernetes

# Deploy
kubectl apply -f k8s-deployment.yaml

# Access via port-forward
kubectl port-forward svc/mcp-terminal-service 3002:3002

# Or via NodePort at http://<node-ip>:30002

Configuration

Create a config.json file:

{
  "default_image": "mcp-example:latest",
  "mcp_servers_config_path": "/mcp-servers.json",
  "network": "mcp-terminal-network",
  "container_template": {
    "environment": {
      "DEBIAN_FRONTEND": "noninteractive",
      "TERM": "xterm-256color"
    },
    "volumes": [
      {
        "host_path": "${PWD}/workspace",
        "container_path": "/workspace",
        "read_only": false
      }
    ],
    "working_dir": "/workspace",
    "command": ["/startup.sh"],
    "exposed_ports": [3001, 8001, 8081],
    "persistent_volume_prefix": "mcp-context-",
    "auto_remove": false
  }
}

Environment Variables

• BIND_ADDRESS - Server bind address (default: 127.0.0.1:3002)
• CONFIG_PATH - Configuration file path (default: config-example.json)
• RUST_LOG - Log level (default: info)

Creating Custom Container Images

Basic Dockerfile

FROM ubuntu:22.04

# Install your tools
RUN apt-get update && apt-get install -y \
    python3 python3-pip git curl jq \
    && rm -rf /var/lib/apt/lists/*

# Create MCP servers configuration
COPY mcp-servers.json /mcp-servers.json

# Create startup script
RUN echo '#!/bin/bash\nsleep infinity' > /startup.sh \
    && chmod +x /startup.sh

WORKDIR /workspace
CMD ["/startup.sh"]

MCP Servers Configuration

Create /mcp-servers.json in your container:

{
  "filesystem": {
    "command": ["python3", "-c"],
    "args": [
      "import json, sys; tools = [{'name': 'read_file', 'description': 'Read file contents', 'inputSchema': {'type': 'object', 'properties': {'path': {'type': 'string'}}, 'required': ['path']}}]; print(json.dumps({'jsonrpc': '2.0', 'result': {'tools': tools}, 'id': json.loads(sys.stdin.read()).get('id')}))"
    ],
    "env": {
      "PYTHONIOENCODING": "utf-8"
    }
  }
}

Build and Use

# Build your custom image
docker build -t my-custom-mcp:latest .

# Update config.json to use your image
{
  "default_image": "my-custom-mcp:latest"
}

# Restart MCP Terminal
./target/release/mcp-terminal

Network Setup

Create the required Docker network:

# Docker
docker network create mcp-terminal-network

# Podman  
podman network create mcp-terminal-network

License

ISC License