MCP 服务器

Command-Line MCP Server

允许人工智能助手通过一个具有全面安全功能的受控界面，安全地执行常见的 Unix/macOS 终端命令。

README

命令行 MCP 服务器

一个用于安全地为 Unix/macOS 系统运行命令行参数的模型控制协议 (MCP) 服务器。

概述

此 MCP 服务器允许 AI 助手通过受控且安全的接口执行常见的 Unix/macOS 终端命令。它支持大约前 40 个最常用的终端命令，并采取适当的安全措施。

特性

安全执行常见的 Unix/macOS 命令
基于命令类型的安全验证
命令分类（读取、写入、系统）
交互式权限管理
基于会话的审批系统
通过环境变量或 JSON 文件进行配置
全面的命令过滤和模式匹配
支持通过管道 (|)、分号 (;) 和与号 (&) 进行命令链接
具有自动批准功能的 Claude Desktop 兼容模式
详细的命令元数据和 AI 助手帮助

支持的命令

读取命令

ls, pwd, cat, less, head, tail, grep, find, which, du, df, file, sort 等。

写入命令

cp, mv, rm, mkdir, rmdir, touch, chmod, chown 等。

系统命令

ps, top, htop, who, netstat, ifconfig, ping 等。

安全特性

用于权限控制的命令分类
阻止危险命令（sudo、eval 等）
模式匹配以防止危险操作
用于持久批准的会话管理
每个会话的权限授予
允许为整个会话授予命令类型批准的选项
自动会话超时
安全处理命令链接（管道、序列等）
可配置的用于不同环境的安全选项

安装

# 克隆仓库
git clone https://github.com/yourusername/cmd-line-mcp.git
cd cmd-line-mcp

# 运行安装脚本 (Linux/macOS)
./install.sh

# 或者手动安装：
python -m venv venv
source venv/bin/activate
pip install -e .
cp config.json.example config.json  # 创建初始配置

用法

运行服务器

# 使用默认配置运行
cmd-line-mcp

# 使用自定义配置文件运行
cmd-line-mcp --config /path/to/config.json

配置

您可以使用三种方法配置服务器：

JSON 配置文件（推荐用于完整配置）
环境变量（用于覆盖特定设置）
.env 文件（用于特定于环境的覆盖）

配置最佳实践：

使用 JSON 配置文件作为您的主要配置方法
使用环境变量或 .env 文件进行特定于环境的覆盖
JSON 提供全面的配置，而环境变量更适合快速覆盖

使用配置文件

基于 config.json.example 中的示例创建一个 JSON 文件：

cp config.json.example config.json
# 编辑 config.json 以自定义设置
cmd-line-mcp --config config.json

配置文件具有以下结构：

{
  "server": {
    "name": "cmd-line-mcp",
    "version": "0.2.0",
    "description": "MCP server for safely executing command-line tools",
    "log_level": "INFO"
  },
  "security": {
    "session_timeout": 3600,
    "max_output_size": 102400,
    "allow_user_confirmation": true,
    "require_session_id": false,
    "allow_command_separators": true
  },
  "commands": {
    "read": [
      "ls", "pwd", "cat", "less", "head", "tail", "grep",
      "find", "which", "du", "df", "file", "sort", "..."
    ],
    "write": [
      "cp", "mv", "rm", "mkdir", "rmdir", "touch", "chmod", "..."
    ],
    "system": [
      "ps", "top", "htop", "who", "netstat", "ifconfig", "..."
    ],
    "blocked": [
      "sudo", "su", "bash", "sh", "zsh", "ksh", "..."
    ],
    "dangerous_patterns": [
      "rm\\s+-rf\\s+/",
      ">\\s+/dev/(sd|hd|nvme|xvd)",
      "..."
    ]
  },
  "output": {
    "max_size": 102400,
    "format": "text"
  }
}

使用环境变量和 .env 文件进行覆盖

虽然建议使用 JSON 配置文件进行全面配置，但您可以使用环境变量或 .env 文件来覆盖特定设置。这对于以下情况特别有用：

部署到不同的环境（开发、测试、生产）
覆盖特定设置而不修改 JSON 文件
设置特定于环境的值，例如日志级别或超时

环境变量示例：

# 覆盖日志级别以进行调试
export CMD_LINE_MCP_SERVER_LOG_LEVEL=DEBUG

# 延长会话超时
export CMD_LINE_MCP_SECURITY_SESSION_TIMEOUT=7200

# 将自定义命令添加到读取命令列表（逗号分隔）
export CMD_LINE_MCP_COMMANDS_READ="wc,nl,column,jq"

cmd-line-mcp --config /path/to/config.json

使用 .env 文件进行覆盖：

创建一个 .env 文件，其中仅包含您要覆盖的设置：

# 设置为 DEBUG 以获取更详细的日志
CMD_LINE_MCP_SERVER_LOG_LEVEL=DEBUG

# 将会话超时延长至 2 小时
CMD_LINE_MCP_SECURITY_SESSION_TIMEOUT=7200

# 为了 Claude Desktop 兼容性
CMD_LINE_MCP_SECURITY_REQUIRE_SESSION_ID=false

使用基本配置和 .env 覆盖运行服务器：

cmd-line-mcp --config /path/to/config.json --env /path/to/.env

配置优先级顺序：

配置方法遵循以下优先级顺序（从最低到最高）：

默认配置（内置）
来自 CMD_LINE_MCP_CONFIG 环境变量的配置文件
来自 --config 参数的配置文件
.env 文件
环境变量（最高优先级）

这意味着环境变量将覆盖 .env 文件中的值，而 .env 文件将覆盖 JSON 配置文件中的值。

与 Claude for Desktop 一起使用

从 https://claude.ai/download 安装 Claude for Desktop
配置 Claude for Desktop 以使用此 MCP 服务器：

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "cmd-line": {
      "command": "/path/to/venv/bin/cmd-line-mcp",
      "args": ["--config", "/path/to/config.json"]
    }
  }
}

您还可以在 Claude Desktop 配置中直接指定环境变量覆盖：

{
  "mcpServers": {
    "cmd-line": {
      "command": "/path/to/venv/bin/cmd-line-mcp",
      "args": ["--config", "/path/to/config.json"],
      "env": {
        "CMD_LINE_MCP_SERVER_LOG_LEVEL": "DEBUG",
        "CMD_LINE_MCP_SECURITY_SESSION_TIMEOUT": "7200",
        "CMD_LINE_MCP_SECURITY_REQUIRE_SESSION_ID": "false"
      }
    }
  }
}

为了与 Claude Desktop 获得最佳兼容性，请确保您的 config.json 中有以下设置：

"security": {
  "require_session_id": false,  // 防止与 Claude Desktop 的审批循环
  "allow_user_confirmation": true
}

重新启动 Claude for Desktop

MCP 工具

此服务器为 AI 助手提供以下 MCP 工具：

execute_command：执行任何支持的命令（需要批准写入/系统命令）
execute_read_command：执行只读命令（无需批准）
list_available_commands：按类别列出所有可用命令
approve_command_type：为当前会话授予命令类型（写入或系统）的批准
get_command_help：获取有关命令功能和示例的详细帮助
get_configuration：获取当前配置设置
update_configuration：在运行时更新配置设置

配置工具详情

get_configuration

此工具检索当前配置设置，包括：

服务器设置（名称、版本、日志级别）
安全设置（会话超时、命令分隔符控制）
命令列表统计信息
输出设置
分隔符支持状态

用法示例：

config = await get_configuration()
print(f"Command separator support: {config['separator_support']}")

update_configuration

此工具允许在运行时动态更新配置：

# 更新安全设置
update_json = '''
{
  "security": {
    "allow_command_separators": false
  }
}
'''
result = await update_configuration(config_updates=update_json, save=False)

# 将新命令添加到读取列表
update_json = '''
{
  "commands": {
    "read": ["ls", "pwd", "cat", "wc", "sort", "head", "tail"]
  }
}
'''
result = await update_configuration(config_updates=update_json, save=True)

config_updates 参数接受带有更新的 JSON 字符串
save 参数确定是否将更改保存到配置文件
更新后，所有命令将立即使用新设置

自定义命令列表

您可以使用配置文件或环境变量覆盖来自定义允许、阻止和分类的命令列表。

使用 JSON 配置

要在 JSON 配置文件中自定义命令：

{
  "commands": {
    "read": [
      "ls", "pwd", "cat", "less", "head", "tail", "grep",
      "wc", "nl", "column", "jq"
    ],
    "system": [
      "ps", "top", "htop", "who", "netstat", "ifconfig", "ping",
      "kubectl", "docker", "aws", "gcloud"
    ],
    "blocked": [
      "sudo", "su", "bash", "sh", "zsh", "ksh", "csh", "fish",
      "npm", "pip", "apt", "apt-get", "yum", "brew"
    ]
  }
}

使用环境变量进行添加

环境变量将与现有命令列表合并（而不是替换）。这允许您添加其他命令而不会丢失默认值：

# 将 awk 和 jq 添加到读取命令列表（它们将与现有命令合并）
export CMD_LINE_MCP_COMMANDS_READ="awk,jq"

# 将容器工具添加到系统命令列表
export CMD_LINE_MCP_COMMANDS_SYSTEM="kubectl,docker,aws"

# 将包管理器添加到阻止的命令列表
export CMD_LINE_MCP_COMMANDS_BLOCKED="npm,pip,apt-get"

在管道中使用这些命令时，它们将被正确识别：

# 现在这将起作用，因为 awk 已添加到允许的命令
ls -la | awk '{print $1}'

# 云/容器命令也将起作用
kubectl get pods | grep "Running"

或者在 .env 文件中：

# 将文本处理工具添加到读取命令
CMD_LINE_MCP_COMMANDS_READ=awk,sed,jq

# 将包管理器添加到阻止的命令
CMD_LINE_MCP_COMMANDS_BLOCKED=npm,pip,apt-get

示例：在 Claude Desktop 配置中使用以访问命令行工具：

{
  "mcpServers": {
    "cmd-line": {
      "command": "/path/to/venv/bin/cmd-line-mcp",
      "args": ["--config", "/path/to/config.json"],
      "env": {
        "CMD_LINE_MCP_COMMANDS_READ": "awk,sed,jq",
        "CMD_LINE_MCP_SERVER_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

这种灵活性允许您：

将自定义命令添加到适当的类别
阻止其他命令
添加新的危险模式以进行匹配
更改安全设置，例如会话超时
启用或禁用命令分隔符支持（管道、分号、与号）
配置 Claude Desktop 兼容性设置

命令链接支持

此服务器支持多种链接命令的方式，所有这些方式都可以在配置中单独启用或禁用：

管道 (|)：将一个命令的输出连接到另一个命令的输入
- 示例：du -h ~/Downloads/* | grep G | sort -hr | head -10
分号 (;)：按顺序运行多个命令
- 示例：mkdir test; cd test; touch file.txt
与号 (&)：在后台运行命令
- 示例：find /large/directory -name "*.log" &

链中的所有命令都必须来自支持的命令列表。

您可以通过多种方式配置命令分隔符支持：

使用配置文件：

"security": {
  "allow_command_separators": true
}

使用环境变量进行快速覆盖：

# 从基本配置文件开始，但覆盖单个设置
export CMD_LINE_MCP_SECURITY_ALLOW_COMMAND_SEPARATORS=false
cmd-line-mcp --config /path/to/config.json

在运行时使用 update_configuration 工具：

update_json = '{"security": {"allow_command_separators": false}}'
await update_configuration(config_updates=update_json)

您还可以将特定分隔符添加到 dangerous_patterns 列表中以单独阻止它们。

许可证

MIT