Terminator

by iris-networks

364 downloads

Not rated

GitHub

About

A lightweight Model Context Protocol (MCP) server written in Go that enables secure terminal command execution on macOS and Linux. Supports persistent shell sessions, configurable timeouts, and both HTTP (StreamableHTTP) and STDIO transports. Designed for AI integrations and auto

Details

Author: iris-networks
Downloads: 364
Categories: Developer Tools, Automation

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Terminator

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "terminator": {
            "terminal": {
                "type": "streamable-http",
                "url": "http://localhost:8080/mcp",
                "command": "docker",
                "args": [
                    "run",
                    "-i",
                    "--rm",
                    "-p",
                    "8080:8080",
                    "-e",
                    "MCP_COMMAND_TIMEOUT=30",
                    "-e",
                    "MCP_SHELL=/bin/bash",
                    "shanurcsenitap/terminator:latest",
                    "--http",
                    "--host",
                    "0.0.0.0",
                    "--port",
                    "8080"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "terminator": {
            "terminal": {
                "type": "streamable-http",
                "url": "http://localhost:8080/mcp",
                "command": "docker",
                "args": [
                    "run",
                    "-i",
                    "--rm",
                    "-p",
                    "8080:8080",
                    "-e",
                    "MCP_COMMAND_TIMEOUT=30",
                    "-e",
                    "MCP_SHELL=/bin/bash",
                    "shanurcsenitap/terminator:latest",
                    "--http",
                    "--host",
                    "0.0.0.0",
                    "--port",
                    "8080"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "terminator": {
            "terminal": {
                "type": "streamable-http",
                "url": "http://localhost:8080/mcp",
                "command": "docker",
                "args": [
                    "run",
                    "-i",
                    "--rm",
                    "-p",
                    "8080:8080",
                    "-e",
                    "MCP_COMMAND_TIMEOUT=30",
                    "-e",
                    "MCP_SHELL=/bin/bash",
                    "shanurcsenitap/terminator:latest",
                    "--http",
                    "--host",
                    "0.0.0.0",
                    "--port",
                    "8080"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "terminator": {
            "terminal": {
                "type": "streamable-http",
                "url": "http://localhost:8080/mcp",
                "command": "docker",
                "args": [
                    "run",
                    "-i",
                    "--rm",
                    "-p",
                    "8080:8080",
                    "-e",
                    "MCP_COMMAND_TIMEOUT=30",
                    "-e",
                    "MCP_SHELL=/bin/bash",
                    "shanurcsenitap/terminator:latest",
                    "--http",
                    "--host",
                    "0.0.0.0",
                    "--port",
                    "8080"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "terminator": {
            "terminal": {
                "type": "streamable-http",
                "url": "http://localhost:8080/mcp",
                "command": "docker",
                "args": [
                    "run",
                    "-i",
                    "--rm",
                    "-p",
                    "8080:8080",
                    "-e",
                    "MCP_COMMAND_TIMEOUT=30",
                    "-e",
                    "MCP_SHELL=/bin/bash",
                    "shanurcsenitap/terminator:latest",
                    "--http",
                    "--host",
                    "0.0.0.0",
                    "--port",
                    "8080"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "terminator": {
            "terminal": {
                "type": "streamable-http",
                "url": "http://localhost:8080/mcp",
                "command": "docker",
                "args": [
                    "run",
                    "-i",
                    "--rm",
                    "-p",
                    "8080:8080",
                    "-e",
                    "MCP_COMMAND_TIMEOUT=30",
                    "-e",
                    "MCP_SHELL=/bin/bash",
                    "shanurcsenitap/terminator:latest",
                    "--http",
                    "--host",
                    "0.0.0.0",
                    "--port",
                    "8080"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "terminator": {
            "terminal": {
                "type": "streamable-http",
                "url": "http://localhost:8080/mcp",
                "command": "docker",
                "args": [
                    "run",
                    "-i",
                    "--rm",
                    "-p",
                    "8080:8080",
                    "-e",
                    "MCP_COMMAND_TIMEOUT=30",
                    "-e",
                    "MCP_SHELL=/bin/bash",
                    "shanurcsenitap/terminator:latest",
                    "--http",
                    "--host",
                    "0.0.0.0",
                    "--port",
                    "8080"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "terminator": {
            "terminal": {
                "type": "streamable-http",
                "url": "http://localhost:8080/mcp",
                "command": "docker",
                "args": [
                    "run",
                    "-i",
                    "--rm",
                    "-p",
                    "8080:8080",
                    "-e",
                    "MCP_COMMAND_TIMEOUT=30",
                    "-e",
                    "MCP_SHELL=/bin/bash",
                    "shanurcsenitap/terminator:latest",
                    "--http",
                    "--host",
                    "0.0.0.0",
                    "--port",
                    "8080"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "terminator": {
            "terminal": {
                "type": "streamable-http",
                "url": "http://localhost:8080/mcp",
                "command": "docker",
                "args": [
                    "run",
                    "-i",
                    "--rm",
                    "-p",
                    "8080:8080",
                    "-e",
                    "MCP_COMMAND_TIMEOUT=30",
                    "-e",
                    "MCP_SHELL=/bin/bash",
                    "shanurcsenitap/terminator:latest",
                    "--http",
                    "--host",
                    "0.0.0.0",
                    "--port",
                    "8080"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "terminator": {
            "terminal": {
                "type": "streamable-http",
                "url": "http://localhost:8080/mcp",
                "command": "docker",
                "args": [
                    "run",
                    "-i",
                    "--rm",
                    "-p",
                    "8080:8080",
                    "-e",
                    "MCP_COMMAND_TIMEOUT=30",
                    "-e",
                    "MCP_SHELL=/bin/bash",
                    "shanurcsenitap/terminator:latest",
                    "--http",
                    "--host",
                    "0.0.0.0",
                    "--port",
                    "8080"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "terminator": {
            "terminal": {
                "type": "streamable-http",
                "url": "http://localhost:8080/mcp",
                "command": "docker",
                "args": [
                    "run",
                    "-i",
                    "--rm",
                    "-p",
                    "8080:8080",
                    "-e",
                    "MCP_COMMAND_TIMEOUT=30",
                    "-e",
                    "MCP_SHELL=/bin/bash",
                    "shanurcsenitap/terminator:latest",
                    "--http",
                    "--host",
                    "0.0.0.0",
                    "--port",
                    "8080"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "terminator": {
            "terminal": {
                "type": "streamable-http",
                "url": "http://localhost:8080/mcp",
                "command": "docker",
                "args": [
                    "run",
                    "-i",
                    "--rm",
                    "-p",
                    "8080:8080",
                    "-e",
                    "MCP_COMMAND_TIMEOUT=30",
                    "-e",
                    "MCP_SHELL=/bin/bash",
                    "shanurcsenitap/terminator:latest",
                    "--http",
                    "--host",
                    "0.0.0.0",
                    "--port",
                    "8080"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "terminator": {
            "terminal": {
                "type": "streamable-http",
                "url": "http://localhost:8080/mcp",
                "command": "docker",
                "args": [
                    "run",
                    "-i",
                    "--rm",
                    "-p",
                    "8080:8080",
                    "-e",
                    "MCP_COMMAND_TIMEOUT=30",
                    "-e",
                    "MCP_SHELL=/bin/bash",
                    "shanurcsenitap/terminator:latest",
                    "--http",
                    "--host",
                    "0.0.0.0",
                    "--port",
                    "8080"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "terminator": {
            "terminal": {
                "type": "streamable-http",
                "url": "http://localhost:8080/mcp",
                "command": "docker",
                "args": [
                    "run",
                    "-i",
                    "--rm",
                    "-p",
                    "8080:8080",
                    "-e",
                    "MCP_COMMAND_TIMEOUT=30",
                    "-e",
                    "MCP_SHELL=/bin/bash",
                    "shanurcsenitap/terminator:latest",
                    "--http",
                    "--host",
                    "0.0.0.0",
                    "--port",
                    "8080"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "terminator": {
            "terminal": {
                "type": "streamable-http",
                "url": "http://localhost:8080/mcp",
                "command": "docker",
                "args": [
                    "run",
                    "-i",
                    "--rm",
                    "-p",
                    "8080:8080",
                    "-e",
                    "MCP_COMMAND_TIMEOUT=30",
                    "-e",
                    "MCP_SHELL=/bin/bash",
                    "shanurcsenitap/terminator:latest",
                    "--http",
                    "--host",
                    "0.0.0.0",
                    "--port",
                    "8080"
                ]
            }
        }
    }
}

From the repository

Build the server with make build, then run it in STDIO mode (default) with ./mcp-terminal-server or in HTTP mode with --http --port 8080. For Claude Desktop, add the binary path and optional environment variables (e.g., MCP_COMMAND_TIMEOUT=30) to your claude_desktop_config.json. Docker images are also available for multi‑architecture deployment.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "terminator": {
            "terminal": {
                "type": "streamable-http",
                "url": "http://localhost:8080/mcp",
                "command": "docker",
                "args": [
                    "run",
                    "-i",
                    "--rm",
                    "-p",
                    "8080:8080",
                    "-e",
                    "MCP_COMMAND_TIMEOUT=30",
                    "-e",
                    "MCP_SHELL=/bin/bash",
                    "shanurcsenitap/terminator:latest",
                    "--http",
                    "--host",
                    "0.0.0.0",
                    "--port",
                    "8080"
                ]
            }
        }
    }
}

McpServers

{
    "terminal": {
        "type": "streamable-http",
        "url": "http://localhost:8080/mcp",
        "command": "docker",
        "args": [
            "run",
            "-i",
            "--rm",
            "-p",
            "8080:8080",
            "-e",
            "MCP_COMMAND_TIMEOUT=30",
            "-e",
            "MCP_SHELL=/bin/bash",
            "shanurcsenitap/terminator:latest",
            "--http",
            "--host",
            "0.0.0.0",
            "--port",
            "8080"
        ]
    }
}

MCP Terminal Server

A Model Context Protocol (MCP) server written in Go that provides secure terminal command execution with configurable timeouts and platform-specific support.

Features

- Cross-platform support: Works on macOS and Linux
- Configurable timeouts: Set custom timeout values for command execution
- Secure execution: Commands run in controlled environment with proper error handling
- Platform-aware: Automatically detects and adapts to the host platform
- Flexible shell support: Configurable shell for command execution
- Multiple transport modes:
- STDIO mode for traditional MCP clients
- 🌐 StreamableHTTP transport: Standards-compliant HTTP-based MCP transport for web integrations
- Flexible session management: Use any session ID you want - no pre-registration required
- 🎉 Persistent shell sessions: Maintain shell state between commands (working directory, environment variables, etc.)

Quick Start

# Build the server
make build
Run in HTTP mode with StreamableHTTP transport
./mcp-terminal-server --http --port 8080
Run in STDIO mode (default)
./mcp-terminal-server

🚀 Quick Testing

Test StreamableHTTP Transport

# Start server in HTTP mode
./mcp-terminal-server --http --port 8080
Test MCP initialization
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}'
Test tools listing (use session ID from initialize response)
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <session-id>" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'
Execute a command
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <session-id>" \
  -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "execute_command", "arguments": {"command": "echo Hello StreamableHTTP!"}}}'

Test Persistent Shell

# Test persistent shell functionality
chmod +x examples/persistent_shell_examples.sh
./examples/persistent_shell_examples.sh

Documentation

📚 Complete Documentation

- Quick Start Guide - Get up and running in minutes
- Getting Started - Comprehensive setup and configuration
- Vercel AI SDK Integration - Connect to Vercel AI SDK
- Architecture Overview - System design and modular structure

Available Tools

1. execute_command - Execute single commands with timeout
2. persistent_shell - Execute commands in persistent shell sessions
3. session_manager - Manage shell sessions (list, close)

Server Endpoints

When running in HTTP mode (--http flag), the server provides:

- POST /mcp - StreamableHTTP transport endpoint for all MCP operations
- Supports initialize, tools/list, tools/call methods
- Requires Mcp-Session-Id header for authenticated requests
- Returns session ID in response headers for initialize calls

MCP Protocol Support

The server implements the Model Context Protocol specification:
- JSON-RPC 2.0 communication
- Session management with UUID-based session IDs
- Tool execution with structured input/output
- Error handling with standard JSON-RPC error codes

Platform Support

- macOS (darwin): Full support - AMD64 & ARM64
- Linux: Full support - AMD64 & ARM64
- Docker: Multi-architecture support via buildx

Integration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "terminal": {
      "command": "/path/to/mcp-terminal-server",
      "env": {
        "MCP_COMMAND_TIMEOUT": "30"
      }
    }
  }
}

Docker

# Run AMD64 image
docker run --rm -p 8080:8080 terminal-mcp:latest-linux-amd64 --http --port 8080
Run ARM64 image  
docker run --rm -p 8080:8080 terminal-mcp:latest-linux-arm64 --http --port 8080
Run with persistent shell session
docker run --rm -p 8080:8080 -v /tmp:/tmp terminal-mcp:latest-linux-amd64 --http --port 8080

Other MCP Clients

The server follows the standard MCP protocol and should work with any compliant MCP client.

Development

Building

# Build for current platform
make build
Build for all platforms
make build-all
Build Docker images
make docker-build
Build and push Docker images
REGISTRY=your-registry.com make docker-push
Build DXT package for distribution
make dxt

Dependencies

- github.com/mark3labs/mcp-go - MCP Go library
- Go 1.23+ (automatically managed)

Production Deployment

For production environments, it's recommended to run the server with proper process management and security measures:

Process Management

- s6: Lightweight process supervision with automatic restart - systemd: Full-featured service management with resource limits - Docker: Containerized deployment with security isolation - Supervisor: Python-based process management

Security Features

- Non-root execution: Run with dedicated user account for limited privileges - Resource limits: CPU, memory, and file access restrictions - Network isolation: Bind to localhost only for enhanced security - AppArmor/SELinux: Additional mandatory access controls - File permissions: Restricted access to necessary directories only

📋 See Process Management Guide for detailed setup instructions

Integration with Iris Agent

This MCP server is used by the Iris Computer Use Agent, our advanced computer use agent for automated terminal interactions.

License

This project is provided as-is for development purposes.

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

MCP Terminal Server

Features

Quick Start

Run in HTTP mode with StreamableHTTP transport

Run in STDIO mode (default)

🚀 Quick Testing

Test StreamableHTTP Transport

Test MCP initialization

Test tools listing (use session ID from initialize response)

Execute a command

Test Persistent Shell

Documentation

Available Tools

Server Endpoints

MCP Protocol Support

Platform Support

Integration

Claude Desktop

Docker

Run ARM64 image

Run with persistent shell session

Other MCP Clients

Development

Building

Build for all platforms

Build Docker images

Build and push Docker images

Build DXT package for distribution

Dependencies

Production Deployment

Process Management

Security Features

Integration with Iris Agent

License

Install

More like this

@mendableai/firecrawl Mcp Server

Umut Naci

Playwright

Sentry

Github

Fetch