MCP 终端服务器

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

特征

• 作为 Windows 服务或以调试模式运行

• 执行 shell 命令并实时传输其输出

• API密钥认证

• 速率限制

• 可通过环境变量或配置文件进行配置

• 强大的错误处理和日志记录

• 失败时自动重新启动进程

Related MCP server: Shell MCP Server

安装

先决条件

• 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 事件查看器中是否存在与服务相关的错误

执照

麻省理工学院