AI导哈

命令执行服务器

MCP命令服务器是一个支持在主机系统上安全执行命令的服务，提供工作目录和标准输入支持，适用于AI助手集成。

  • by brunorozendo
  • Java
  • 本地部署
  • 更新于
在 GitHub 查看 brunorozendo/mcp-server-command

使用说明

MCP命令服务器

一种模型上下文协议（MCP）服务器，可在主机系统上安全执行命令。该服务器允许像Claude这样的AI助手运行shell命令，并支持可选的工作目录和stdin。

该项目现在已模块化，以支持多种传输方法：stdio、HTTP和服务器发送事件（SSE）。

特性

  • 命令执行：在主机系统上运行任何shell命令
  • 工作目录支持：在特定目录中执行命令
  • STDIN支持：将输入数据传输到命令
  • 交叉平台的：适用于macOS、Linux和Windows
  • 超时保护：命令在60秒后超时以防止挂起
  • 特殊鱼壳支持：加强对鱼壳的处理
  • 高级日志记录：由Logback提供支持，具有可配置的日志级别（ERROR、WARN、INFO、DEBUG、TRACE）、可选的文件日志记录和滚动文件支持

先决条件

  • Java 25或更高版本
  • Gradle（用于从源头构建）
  • Claude桌面应用程序（用于集成）

安装

从源头构建

  1. 克隆存储库：
git clone <repository-url>
cd mcp-server-command
  1. 构建项目：
./gradlew build

这将为每个模块创建JAR文件：

  • stdio/build/libs/stdio-1.0.0.jar -标准I/O传输（建议用于Claude Desktop）
  • http/build/libs/http-1.0.0.jar -HTTP传输
  • sse/build/libs/sse-1.0.0.jar -服务器发送事件传输

原生二进制（可选）

为了获得更好的性能，您可以使用GraalVM构建本机二进制文件：

./gradlew stdio:nativeCompile

这将在以下位置创建一个本机可执行文件 stdio/build/native/nativeCompile/mcp-server-command

预构建JAR

如果您有一个预构建的JAR，请跳过构建步骤并继续配置。

配置

Claude桌面集成

  1. 找到您的Claude Desktop配置：

    • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
    • 窗户： %APPDATA%\Claude\claude_desktop_config.json
    • Linux： ~/.config/Claude/claude_desktop_config.json

  2. 添加MCP服务器配置：

选项A:Java JAR（推荐）

{
  "mcpServers": {
    "mcp-server-command": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/stdio-1.0.0.jar"
      ],
      "env":{
        "LOG_DIR":"/Users/<username>/Library/Logs/Claude",
        "LOG_LEVEL":"DEBUG"
      }
    }
  }
}

选项B：原生二进制

{
  "mcpServers": {
    "mcp-server-command": {
      "command": "/absolute/path/to/stdio/build/native/nativeCompile/mcp-server-command",
      "env":{
        "LOG_DIR":"/Users/<username>/Library/Logs/Claude",
        "LOG_LEVEL":"DEBUG"
      }
    }
  }
}
  1. 重新启动Claude Desktop以加载新服务器

用法

配置后，Claude可以使用 run_command 在您的系统上执行命令的工具。

基本示例

简单命令执行：

Run the command: ls -la

带工作目录的命令：

Run 'git status' in the directory /Users/username/my-project

带有stdin的命令：

Create a new file called hello.txt with the content "Hello, World!" using the cat command

Python脚本执行：

Run this Python script:
print("Hello from Python")
for i in range(5):
    print(f"Count: {i}")

api参考

工具：run_command

在主机系统上执行命令。

参数：

  • command （string，必填）：使用参数执行的命令
  • workdir （string，可选）：命令执行的工作目录
  • stdin （string，可选）：将文本导入命令的STDIN

退货：

  • stdout：命令的标准输出
  • stderr：命令输出的标准错误
  • message：如果命令失败，则显示错误消息
  • isError：布尔值，指示命令是否失败

请求示例：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "run_command",
    "arguments": {
      "command": "echo Hello World",
      "workdir": "/tmp",
      "stdin": "Input data"
    }
  }
}

发展

项目结构

mcp-server-command/
├── stdio/                      # Standard I/O transport module
│   ├── src/main/java/com/brunorozendo/mcp/
│   │   └── McpServer.java      # Main server entry point
│   └── build.gradle
├── http/                       # HTTP transport module  
│   ├── src/main/java/com/brunorozendo/mcp/
│   │   └── McpServer.java      # HTTP server implementation
│   └── build.gradle
├── sse/                        # Server-Sent Events transport module
│   ├── src/main/java/com/brunorozendo/mcp/
│   │   └── McpServer.java      # SSE server implementation  
│   └── build.gradle
├── tools/                      # Shared command execution logic
│   ├── src/main/java/com/brunorozendo/mcp/
│   │   ├── CommandExecutor.java     # Command execution logic
│   │   ├── CommandResult.java       # Result data structure
│   │   ├── ExecCommandTool.java     # Tool implementation
│   │   ├── Transport.java           # Transport configuration
│   │   └── ToolSchemas.java         # Tool schema definitions
│   └── build.gradle
├── settings.gradle             # Multi-module configuration
└── docs/                       # Documentation

运行测试

执行测试脚本以验证功能：

./test_server.sh

建立分销

创建分发存档（ZIP和TAR）：

./gradlew distZip distTar

安全注意事项

⚠️ 警告：此服务器以与运行Java进程的用户相同的权限执行命令。

安全最佳实践：

  1. 仅当您信任AI助手时才安装此服务器
  2. 以最低限度的必要权限运行服务器
  3. 考虑为服务器使用受限用户帐户
  4. 共享屏幕或命令输出时要小心
  5. 定期检查正在执行的命令
  6. 考虑实施命令白名单以供生产使用

潜在风险：

  • 文件系统访问和修改
  • 网络操作
  • 流程执行
  • 访问环境变量和系统信息

故障排除

服务器未出现在Claude中

  1. 验证配置文件路径是否正确
  2. 确保JAR文件路径是绝对的，而不是相对的
  3. 检查是否安装了Java 25+： java -version
  4. 配置更改后重新启动Claude Desktop

命令失败

  1. 将日志级别设置为DEBUG或TRACE以查看详细的错误消息
  2. 检查工作目录的文件权限
  3. 验证命令语法是否适用于您的shell
  4. 首先直接在终端中测试命令

超时错误

  • 60秒后命令超时
  • 对于长时间运行的命令，考虑将其分解为更小的步骤
  • 谨慎使用后台进程

高级用法

创建文件

# Using cat with stdin
echo "File content" | cat > newfile.txt

# Or directly with stdin parameter
cat > newfile.txt
# with stdin: "File content"

运行脚本

# Python
python3 -c "print('Hello')"

# Or with stdin for longer scripts
python3
# with stdin: <your script content>

鱼壳支持

服务器包括对Fish shell的特殊处理，以正确处理stdin：

fish -c "echo $USER"

版本历史

  • 1.0.0 -当前版本采用模块化架构
    • 模块化设计，支持stdio、HTTP和SSE传输
    • 具有超时保护的命令执行
    • 工作目录支持
    • STDIN支持
    • 特殊鱼壳处理
    • 高级基于Logback的日志记录，支持文件轮换
    • 更新到MCP SDK 0.17.0
    • Java 25支持
    • GraalVM原生编译支持

自定义日志备份配置

对于高级用户，您可以提供自己的 logback.xml 配置文件：

  1. 创建您的自定义 logback.xml
  2. 将其放置在类路径中或使用指定其位置 -Dlogback.configurationFile=/path/to/logback.xml

许可证

[在此处添加您的许可证信息]

贡献

[如适用，添加捐款指南]

支持

对于问题和疑问：

  • 检查故障排除部分
  • 为调试设置适当的日志级别
  • [添加支持联系人/存储库问题链接]

相关 MCP