AI导哈

终端命令服务器

一个轻量级的FastAPI服务器，可作为Windows服务运行，提供执行Shell命令并实时流式传输输出的端点。

  • by cwmoore-ai
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 cwmoore-ai/mcp-terminal-server

使用说明

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：执行命令

    • 需要API密钥 X-API-Key 头球
    • 请求正文： {"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事件查看器是否存在与服务相关的错误

许可证

麻省理工学院

相关 MCP