MCP Terminal Server

by cwmoore-ai
MIT License

Integrations

  • Provides a lightweight server implementation that exposes an endpoint to execute shell commands and stream their output in real-time.

  • Leverages Python 3.7+ to provide a Windows service that can execute commands with robust error handling, logging, and automatic process restart capabilities.

  • Enables remote execution of shell commands with streaming output, allowing for running and monitoring command-line operations through an authenticated API.

MCP 终端服务器

轻量级的 FastAPI 服务器,可以作为 Windows 服务运行,并公开一个端点来执行 shell 命令并流式传输其输出。

特征

  • 作为 Windows 服务或以调试模式运行
  • 执行 shell 命令并实时传输其输出
  • API密钥认证
  • 速率限制
  • 可通过环境变量或配置文件进行配置
  • 强大的错误处理和日志记录
  • 失败时自动重新启动进程

安装

先决条件

  • Windows操作系统
  • Python 3.7 或更高版本
  • 管理员权限(用于服务安装)

安装步骤

  1. 克隆此存储库或下载源代码
  2. 以管理员身份打开 PowerShell
  3. 导航到项目目录
  4. 运行安装脚本:
.\install_service.ps1

这将:

  • 安装所需的 Python 依赖项
  • 生成随机 API 密钥(或使用您提供的密钥)
  • 创建配置文件
  • 安装并启动 Windows 服务

安装选项

您可以使用以下参数自定义安装:

.\install_service.ps1 -ApiKey "your-api-key" -Port 8080 -Host "127.0.0.1" -LogLevel "debug"

可用参数:

  • -ApiKey :用于身份验证的自定义 API 密钥
  • -Port :服务器的端口号(默认值:8000)
  • -Host :绑定到的主机地址(默认值:0.0.0.0)
  • -LogLevel :日志级别(调试、信息、警告、错误、严重)
  • -ConfigFile :自定义配置文件的路径

配置

可以通过以下方式配置服务器:

  1. 环境变量
  2. 配置文件(config.json)
  3. 安装期间的命令行参数

配置文件

提供了一个示例配置文件( config.json.sample )。您可以将其复制到config.json并进行修改:

{ "host": "0.0.0.0", "port": 8000, "log_level": "info", "log_file": "mcp_terminal_server.log", "max_log_size_mb": 10, "log_backup_count": 5, "restart_on_failure": true, "max_restart_attempts": 5, "restart_delay_seconds": 10, "shutdown_timeout_seconds": 30, "working_directory": null }

环境变量

您还可以使用环境变量配置服务器:

  • MCP_TERMINAL_API_KEY :用于身份验证的 API 密钥
  • MCP_HOST :绑定到的主机地址
  • MCP_PORT :服务器的端口号
  • MCP_LOG_LEVEL :日志级别
  • MCP_LOG_FILE :日志文件路径
  • MCP_MAX_LOG_SIZE_MB :最大日志文件大小(以 MB 为单位)
  • MCP_LOG_BACKUP_COUNT :要保留的日志备份文件的数量
  • MCP_RESTART_ON_FAILURE :失败时是否重新启动服务器
  • MCP_MAX_RESTART_ATTEMPTS :重启尝试的最大次数
  • MCP_RESTART_DELAY_SECONDS :重启尝试之间的延迟
  • MCP_SHUTDOWN_TIMEOUT_SECONDS :正常关机超时
  • MCP_WORKING_DIRECTORY :服务器的工作目录

服务管理

服务命令

可以使用以下命令管理该服务:

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

日志

日志存储在配置的日志文件中(默认值: mcp_terminal_server.log )。日志包括:

  • 服务启动/停止事件
  • 命令执行
  • 错误和警告
  • 健康检查结果

API 使用

测试客户端

提供了一个强大的测试客户端来与服务器交互,具有以下功能:

  • 命令行参数以提高可用性
  • API密钥认证支持
  • 彩色输出,更易读
  • 支持将输出保存到文件
  • 强大的错误处理和日志记录
  • 具有命令历史记录的交互模式
  • 服务器健康检查功能
基本用法
# Run a command python test_client.py -c "dir" -k "your-api-key" # Check server health python test_client.py --health # Interactive mode python test_client.py -k "your-api-key" # Save output to a file python test_client.py -c "systeminfo" --save-output output.txt # Specify server URL python test_client.py -s "http://example.com:8000" -c "dir" # Enable verbose output python test_client.py -v -c "dir" # Show version python test_client.py --version
配置文件

可以使用 JSON 配置文件来配置测试客户端。根据提供的示例创建一个client_config.json文件:

{ "server_url": "http://localhost:8000", "api_key": "your-api-key-here", "timeout": 60, "verbose": false }

然后使用它:

python test_client.py --config client_config.json
环境变量

测试客户端还支持通过环境变量进行配置:

  • MCP_TERMINAL_API_KEY :用于身份验证的 API 密钥
  • MCP_TERMINAL_SERVER_URL :服务器 URL

API 端点

  • POST /run :执行命令
    • 需要X-API-Key标头中的 API 密钥
    • 请求正文: {"command": "your command"}
    • 返回带有命令输出的流式响应
  • GET /health :检查服务器健康状况
    • 返回{"status": "healthy", "active_sessions": 0}

安全注意事项

  • 在生产环境中始终更改默认 API 密钥
  • 如果服务器只能在本地访问,则将主机限制为127.0.0.1
  • 考虑在生产中使用 HTTPS
  • 服务器阻止潜在的危险命令,但可能需要额外的安全措施

故障排除

  • 检查日志文件中是否存在错误
  • 在调试模式下运行以查看控制台输出: python service.py debug
  • 验证服务是否正在运行: Get-Service -Name "MCP_Terminal_Server"
  • 检查 Windows 事件查看器中是否存在与服务相关的错误

执照

麻省理工学院

-
security - not tested
A
license - permissive license
-
quality - not tested

轻量级 FastAPI 服务器,允许在 Windows 上远程执行 shell 命令,具有实时输出流和 API 密钥认证和速率限制等安全功能。

  1. 特征
    1. 安装
      1. 先决条件
      2. 安装步骤
      3. 安装选项
    2. 配置
      1. 配置文件
      2. 环境变量
    3. 服务管理
      1. 服务命令
      2. 日志
    4. API 使用
      1. 测试客户端
      2. API 端点
    5. 安全注意事项
      1. 故障排除
        1. 执照

          Related MCP Servers

          • A
            security
            A
            license
            A
            quality
            A secure shell command execution server implementing the Model Context Protocol (MCP). This server allows remote execution of whitelisted shell commands with support for stdin input.
            Last updated -
            1
            68
            Python
            MIT License
            • Apple
          • A
            security
            F
            license
            A
            quality
            A CLI command execution server that enables running shell commands with structured output, providing detailed execution results including stdout, stderr, exit code, and execution duration.
            Last updated -
            2
            16
            TypeScript
            • Apple
          • -
            security
            A
            license
            -
            quality
            A Model Context Protocol server that enables remote execution of shell commands across different operating systems, automatically handling platform-specific differences between Windows and Unix-like systems.
            Last updated -
            JavaScript
            MIT License
            • Linux
          • -
            security
            A
            license
            -
            quality
            An MCP server that enables secure execution of shell commands across Windows, macOS, and Linux with built-in whitelisting and approval mechanisms for enhanced security.
            Last updated -
            13
            JavaScript
            MIT License
            • Linux
            • Apple

          View all related MCP servers

          ID: k4nfeggzg0