Shell Operations MCP Server

一个功能完整的 Shell 运维操作 MCP 服务器，基于 FastMCP + uv 构建，提供系统监控、进程管理、网络诊断、日志分析等能力。

📖 5 分钟快速开始 | 使用指南 | 项目总结

特性

• 🚀 FastMCP 框架 - 简洁高效的 MCP 实现
• 📦 uv 包管理 - 快速依赖管理和虚拟环境
• 🔒 安全模式 - 内置安全机制，防止危险操作
• 📊 跨平台监控 - 基于 psutil，支持 macOS/Linux/Windows
• 🛠️ 40+ 工具 - 涵盖系统监控、进程管理、网络诊断、日志分析等
• 🎯 零配置 - 使用 uvx 无需安装即可运行
• 📝 结构化输出 - 所有工具返回 JSON 格式，易于解析

功能模块

1. 系统资源监控

• get_memory_info - 内存使用情况（总量/已用/可用/缓存）
• get_cpu_load - CPU 负载（1/5/15分钟平均值）
• get_disk_usage - 磁盘使用率（所有挂载点）
• get_io_stats - I/O 统计信息
• get_system_uptime - 系统运行时间

2. 进程管理

• list_processes - 列出进程（支持过滤）
• get_process_info - 获取进程详细信息
• get_process_files - 查看进程打开的文件
• kill_process - 终止进程（需确认）
• get_top_processes - 获取资源占用 TOP N 进程

3. 网络诊断

• check_port_listening - 检查端口监听状态
• test_connectivity - 测试网络连通性（ping/curl）
• dns_lookup - DNS 解析查询
• get_network_stats - 网络流量统计
• test_tls_connection - TLS/SSL 握手测试

4. 文件与目录操作

• get_file_info - 文件详细信息（大小/权限/时间）
• get_directory_size - 目录大小统计
• calculate_file_hash - 文件哈希校验（md5/sha256）
• search_files - 文件搜索（支持正则）
• get_file_permissions - 查看文件权限和 ACL

5. 环境变量管理

• get_env_var - 读取环境变量
• set_env_var - 设置环境变量（会话级）
• list_env_vars - 列出所有环境变量
• export_env_to_file - 导出环境变量到文件

6. 日志与文本处理

• tail_log - 实时查看日志尾部
• grep_log - 日志关键字搜索
• count_pattern - 统计模式匹配次数
• extract_log_slice - 提取日志片段（按行号/时间）
• parse_json_log - 解析 JSON 格式日志

7. 服务与包管理

• check_service_status - 检查服务状态（systemd/launchd）
• list_installed_packages - 列出已安装包
• check_docker_status - Docker 容器状态
• get_package_version - 查询包版本

8. 健康检查与探针

• http_health_check - HTTP 健康检查
• database_health_check - 数据库连接测试
• system_health_report - 系统综合健康报告
• custom_health_script - 执行自定义健康检查脚本

9. 配置与部署

• generate_config_file - 生成配置文件模板
• compress_directory - 压缩目录
• extract_archive - 解压文件
• cleanup_temp_files - 清理临时文件

10. 安全与审计

• check_open_ports - 扫描开放端口
• get_failed_login_attempts - 获取失败登录记录
• check_file_integrity - 文件完整性检查
• audit_user_permissions - 审计用户权限

快速开始

1. 安装 uv（如果还没有）

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或使用 Homebrew
brew install uv

2. 安装依赖

cd python/shell_ops_mcp
uv sync

3. 本地测试

# 直接运行测试
uv run python test_local.py

# 或进入虚拟环境
uv run shell-ops-mcp

MCP 配置

在 Kiro 的 .kiro/settings/mcp.json 中添加：

方式 1: 使用 uvx（推荐，无需安装）

{
  "mcpServers": {
    "shell-ops": {
      "command": "uvx",
      "args": [
        "--from",
        "/Users/你的用户名/项目路径/python/shell_ops_mcp",
        "shell-ops-mcp"
      ],
      "env": {
        "SHELL_OPS_SAFE_MODE": "true",
        "SHELL_OPS_TIMEOUT": "30",
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": [
        "get_memory_info",
        "get_cpu_load",
        "get_system_info",
        "get_disk_usage",
        "list_env_vars"
      ]
    }
  }
}

方式 2: 使用 uv run

{
  "mcpServers": {
    "shell-ops": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/你的用户名/项目路径/python/shell_ops_mcp",
        "shell-ops-mcp"
      ],
      "env": {
        "SHELL_OPS_SAFE_MODE": "true"
      }
    }
  }
}

安全特性

• 命令白名单机制
• 危险操作需要确认
• 资源使用限制（超时/内存）
• 审计日志记录
• 沙箱模式支持

使用示例

# 获取系统健康报告
result = await mcp.call_tool("system_health_report")

# 检查端口
result = await mcp.call_tool("check_port_listening", {"port": 8080})

# 搜索日志
result = await mcp.call_tool("grep_log", {
    "file": "/var/log/app.log",
    "pattern": "ERROR",
    "lines": 50
})