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 
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

1. 添加MCP服务器配置：

选项A:Java JAR（推荐）

{
  "mcpServers": {
    "mcp-server-command": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/stdio-1.0.0.jar"
      ],
      "env":{
        "LOG_DIR":"/Users//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//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: 

鱼壳支持

服务器包括对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

许可证

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

贡献

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

支持

对于问题和疑问：

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