What is the MCP Terminal Server?

The MCP Terminal Server is a lightweight FastAPI server that runs as a Windows service. It allows you to execute shell commands and stream their output in real-time through an API endpoint.

What are the prerequisites for installing the MCP Terminal Server?

You need a Windows operating system, Python 3.7 or higher, and administrator privileges to install the MCP Terminal Server.

How do I install the MCP Terminal Server?

To install, clone the repository, open PowerShell as Administrator, navigate to the project directory, and run the `install_service.ps1` script.

Can I customize the installation?

Yes, you can customize the installation by using parameters such as -ApiKey, -Port, -Host, -LogLevel, and -ConfigFile when running the installation script.

What environment variables can I use to configure the server?

You can use environment variables such as MCP_TERMINAL_API_KEY, MCP_HOST, MCP_PORT, MCP_LOG_LEVEL, and others to configure the server.

How do I manage the MCP Terminal Server service?

You can manage the service using PowerShell commands like python service.py install, python service.py start, python service.py stop, and others.

Where are the logs stored?

Logs are stored in the configured log file, which defaults to mcp_terminal_server.log.

How do I use the API?

You can use the API by sending a POST request to the /run endpoint with the command to execute in the request body. You need to include an API key in the X-API-Key header.

Is there a test client available?

Yes, a test client (test_client.py) is provided to interact with the server. It supports command-line arguments, API key authentication, and more.

How do I configure the test client?

You can configure the test client using a JSON configuration file (client_config.json) or environment variables.

What security considerations should I keep in mind?

Always change the default API key in production, restrict the host to 127.0.0.1 if the server should only be accessible locally, and consider using HTTPS in production.

What do I do if I encounter issues?

Check the log file for errors, run in debug mode (python service.py debug), verify the service is running, and check the Windows Event Viewer for service-related errors.

MCP Terminal Server – Overview

Q: How can I configure the server?

You can configure the server through environment variables, a configuration file (config.json), or command-line arguments during installation.

UBOS Asset Marketplace: MCP Terminal Server - Unleash Command Execution Power with Secure Remote Access

In the dynamic landscape of modern computing, the ability to remotely execute commands on servers and systems is paramount. UBOS is proud to present the MCP Terminal Server, a lightweight yet powerful solution designed to provide seamless command execution and real-time output streaming. Built on the robust FastAPI framework and engineered for Windows environments, the MCP Terminal Server is an indispensable asset for developers, system administrators, and anyone requiring secure and efficient remote command execution.

What is MCP and Why It Matters?

Before diving into the intricacies of the MCP Terminal Server, it’s crucial to understand the significance of MCP (Model Context Protocol). MCP is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). In essence, it acts as a bridge, enabling AI models to access and interact with external data sources and tools. This interaction empowers AI agents to perform complex tasks, make informed decisions, and automate processes with unprecedented efficiency. By integrating MCP servers, organizations can unlock the full potential of AI, driving innovation and gaining a competitive edge.

Core Functionality

The MCP Terminal Server is designed with simplicity and functionality at its core. It exposes an endpoint that allows users to execute shell commands and receive their output in real-time. This capability opens a wide array of possibilities, from automating routine tasks to troubleshooting critical system issues.

Key Features:

Lightweight and Efficient: Built on FastAPI, the server is optimized for performance and minimal resource consumption.
Windows Service Integration: Seamlessly runs as a Windows service, ensuring continuous availability and reliability.
Real-Time Output Streaming: Provides real-time feedback, allowing users to monitor command execution progress.
API Key Authentication: Secures access with API key authentication, preventing unauthorized command execution.
Rate Limiting: Protects against abuse and ensures fair resource allocation through configurable rate limiting.
Configurable: Easily customizable via environment variables or configuration files.
Robust Error Handling and Logging: Comprehensive error handling and logging facilitate quick issue identification and resolution.
Automatic Process Restart: Automatically restarts processes on failure, ensuring uninterrupted service.

Use Cases

The versatility of the MCP Terminal Server makes it suitable for a wide range of applications. Here are a few notable use cases:

Remote System Administration: System administrators can remotely execute commands on Windows servers, perform maintenance tasks, and troubleshoot issues without needing direct access to the server console.
Automated Task Execution: Developers can automate routine tasks, such as deploying applications, running scripts, and performing system backups, through automated command execution.
Continuous Integration and Continuous Deployment (CI/CD): Integrate the MCP Terminal Server into CI/CD pipelines to automate build processes, run tests, and deploy applications to Windows servers.
Monitoring and Diagnostics: Monitor system health, collect performance metrics, and diagnose issues by executing diagnostic commands and analyzing the output in real-time.
Security Auditing: Perform security audits and compliance checks by executing security-related commands and analyzing the results.

Key Benefits

Enhanced Productivity: Automate routine tasks and reduce manual intervention, freeing up valuable time and resources.
Improved Efficiency: Execute commands remotely and receive real-time feedback, enabling faster troubleshooting and resolution of issues.
Increased Security: Secure access with API key authentication and rate limiting, protecting against unauthorized command execution and abuse.
Simplified Management: Easily manage and configure the server through environment variables or configuration files.
Reliable Operation: Ensure continuous availability with Windows service integration and automatic process restart.

Technical Deep Dive

Installation

Installing the MCP Terminal Server is straightforward and can be accomplished in a few simple steps:

Prerequisites: Ensure you have a Windows operating system, Python 3.7 or higher, and administrator privileges.
Clone the Repository: Clone the repository or download the source code from the UBOS Asset Marketplace.
Open PowerShell as Administrator: Launch PowerShell with administrator privileges.
Navigate to the Project Directory: Change the directory to the project folder.
Run the Installation Script: Execute the install_service.ps1 script. This script installs the necessary Python dependencies, generates a random API key, creates a configuration file, and installs and starts the Windows service.

Configuration

The MCP Terminal Server offers extensive configuration options to tailor the server to your specific needs. Configuration can be achieved through environment variables, a configuration file (config.json), or command-line arguments during installation.

Configuration File:

A sample configuration file (config.json.sample) is provided. Copy this file to config.json and modify it to suit your requirements. The configuration file allows you to specify parameters such as the host address, port number, log level, log file path, and more.

Environment Variables:

Environment variables provide a flexible way to configure the server. Supported environment variables include:

MCP_TERMINAL_API_KEY: API key for authentication
MCP_HOST: Host address to bind to
MCP_PORT: Port number for the server
MCP_LOG_LEVEL: Log level
MCP_LOG_FILE: Path to log file
MCP_MAX_LOG_SIZE_MB: Maximum log file size in MB
MCP_LOG_BACKUP_COUNT: Number of log backup files to keep
MCP_RESTART_ON_FAILURE: Whether to restart the server on failure
MCP_MAX_RESTART_ATTEMPTS: Maximum number of restart attempts
MCP_RESTART_DELAY_SECONDS: Delay between restart attempts
MCP_SHUTDOWN_TIMEOUT_SECONDS: Timeout for graceful shutdown
MCP_WORKING_DIRECTORY: Working directory for the server

Service Management

The MCP Terminal Server can be managed using PowerShell commands. Here are some essential service management commands:

python service.py install: Install the service
python service.py start: Start the service
python service.py stop: Stop the service
python service.py restart: Restart the service
python service.py remove: Remove the service
python service.py update: Update the service configuration
python service.py debug: Run in debug mode (not as a service)

API Usage

The MCP Terminal Server exposes a simple yet powerful API for executing commands and checking server health.

API Endpoints:

POST /run: Execute a command. Requires an API key in the X-API-Key header and a JSON body with the command to execute.
GET /health: Check server health. Returns a JSON response indicating the server status and active sessions.

A test client is provided to interact with the server. The test client supports command-line arguments, API key authentication, colored output, and more.

Integration with UBOS Platform

The MCP Terminal Server seamlessly integrates with the UBOS platform, a full-stack AI Agent development environment. UBOS empowers businesses to orchestrate AI Agents, connect them with enterprise data, build custom AI Agents with their own LLM models, and create sophisticated Multi-Agent Systems.

By integrating the MCP Terminal Server into the UBOS platform, organizations can enhance the capabilities of their AI Agents, enabling them to interact with Windows systems, automate tasks, and access valuable data. This integration creates a powerful synergy that drives innovation and improves operational efficiency.

Security Considerations

Security is paramount when implementing remote command execution solutions. The MCP Terminal Server incorporates several security measures to protect against unauthorized access and abuse. These include:

API Key Authentication: All API requests require a valid API key in the X-API-Key header.
Rate Limiting: Rate limiting protects against brute-force attacks and ensures fair resource allocation.
Restricted Host Access: Restricting the host to 127.0.0.1 limits access to the server to local connections only.

Additionally, it is recommended to use HTTPS in production to encrypt communication between clients and the server. Always change the default API key to a strong, unique value.

Conclusion

The UBOS Asset Marketplace’s MCP Terminal Server is a robust and versatile solution for remote command execution on Windows systems. Its lightweight design, comprehensive feature set, and seamless integration with the UBOS platform make it an invaluable asset for developers, system administrators, and AI practitioners. By leveraging the power of the MCP Terminal Server, organizations can enhance productivity, improve efficiency, and unlock new possibilities in automation and AI.

Take control of your Windows systems with the MCP Terminal Server and experience the power of secure, efficient remote command execution.