使用说明

项目简介

该项目 'mcp-shell' 提供了一个基于 Model Context Protocol (MCP) 的服务器实现，它允许大型语言模型（LLM）通过一个名为 'run_command' 的工具，安全地执行shell命令。该服务器旨在弥合 LLM 与本地操作系统之间的鸿沟，使 LLM 能够执行如文件系统操作、系统查询等任务，同时通过黑名单和命令验证机制保障安全性。特别针对与 Claude Desktop 的集成进行了优化，方便用户将本地shell功能接入 Claude。

主要功能点

MCP协议兼容: 完全实现了 Model Context Protocol 服务器端规范，能够与任何 MCP 客户端（如 Claude Desktop）进行标准化的通信。
安全Shell命令执行: 提供 'run_command' 工具，允许 LLM 执行 shell 命令，但内置多重安全机制：
- 命令黑名单: 阻止执行包括文件系统破坏、权限提升、系统控制等危险命令，防止恶意操作。
- 命令存在性验证: 执行命令前验证命令是否存在于系统路径中，避免执行不存在的或拼写错误的命令。
标准I/O传输: 使用标准输入/输出 (stdio) 作为 MCP 服务器的通信通道，简化部署和集成。
错误处理: 提供全面的错误处理机制，包括命令未找到、命令被阻止、执行错误和协议错误等，方便调试和问题排查。
可扩展性: 允许开发者通过修改黑名单、验证规则和命令解析逻辑，定制服务器的安全策略和功能。

安装步骤

安装 Node.js 和 npm: 确保你的系统已安装 Node.js 和 npm (Node.js 包管理器)。你可以从 nodejs.org 下载并安装。
运行 'npx mcp-shell': 在终端中执行命令 'npx mcp-shell' 即可启动 MCP 服务器。'npx' 是 npm 自带的包执行器，它会自动下载并运行 'mcp-shell' 包。

服务器配置

MCP 服务器主要供 MCP 客户端使用，例如 Claude Desktop。要将 'mcp-shell' 添加到 Claude Desktop，你需要配置 Claude Desktop 的 MCP 服务器列表。配置信息通常以 JSON 格式存在于 Claude Desktop 的配置文件中。

配置信息 (JSON 格式):

{
  "mcpServers": {
    "shell-server": {
      "command": "npx",
      "args": ["mcp-shell"]
    }
  }
}

配置参数说明:

'"shell-server"': 服务器名称，可以自定义，用于在 Claude Desktop 中标识该服务器。
'"command"': 启动 MCP 服务器的命令。这里设置为 '"npx"'，表示使用 'npx' 命令。
'"args"': 命令参数，是一个字符串数组。这里设置为 '["mcp-shell"]'，表示 'npx' 需要执行的包是 'mcp-shell'。

Claude Desktop 配置 (自动配置):

为了简化配置，'mcp-shell' 提供了自动配置命令：

运行 'npx mcp-shell config': 在终端中执行 'npx mcp-shell config' 命令。该命令会自动检测你的操作系统，找到 Claude Desktop 的配置文件，并将上述 JSON 配置信息添加到配置文件中。
重启 Claude Desktop: 配置完成后，你需要重启 Claude Desktop 才能使配置生效。

手动配置 (如果自动配置失败或需要自定义):

查找配置文件路径: 根据你的操作系统，找到 Claude Desktop 的配置文件 'claude_desktop_config.json'。
- macOS: '~/Library/Application Support/Claude/claude_desktop_config.json'
- Windows: '%APPDATA%\Claude\claude_desktop_config.json'
编辑配置文件: 使用文本编辑器打开 'claude_desktop_config.json' 文件。
添加 MCP 服务器配置: 在 JSON 对象的 '"mcpServers"' 字段下（如果没有则创建），添加上述 JSON 配置信息。注意 JSON 格式的正确性，避免语法错误。

基本使用方法

启动 MCP 服务器: 按照安装步骤启动 'mcp-shell' 服务器。
启动 Claude Desktop 并连接: 启动 Claude Desktop，如果配置正确，你应该能在 Claude Desktop 的界面中看到名为 "shell-server" 的 MCP 工具。
在 Claude 中使用 'run_command' 工具: 在 Claude 的对话中，你可以指示 Claude 使用 'run_command' 工具来执行 shell 命令。例如，你可以说 "请使用 shell-server 的 run_command 工具执行 'ls -l' 命令"。
查看命令结果: Claude 会调用 'mcp-shell' 服务器执行 'ls -l' 命令，并将命令的输出结果返回给你。

工具 'run_command' 的输入和输出:

输入 (JSON):

{
  "command": "要执行的shell命令"
}

例如: '{"command": "ls -l"}'

输出 (纯文本): shell 命令执行的输出结果，或错误信息。

注意事项

安全性: 虽然 'mcp-shell' 提供了黑名单和命令验证等安全机制，但执行 shell 命令仍然存在潜在风险。请谨慎使用，并理解安全风险。
命令黑名单: 你可以通过修改 'src/index.ts' 文件中的 'BLACKLISTED_COMMANDS' 集合来定制命令黑名单。
错误日志: MCP 服务器的错误信息会输出到终端的 'stderr' (标准错误输出)。

关键词