Claude Command Runner

🚀 Claude Command Runner

Claude Command Runner 是一款强大的模型上下文协议（MCP）服务器，它架起了 Claude Desktop 与终端应用之间的桥梁，支持无缝执行命令，智能获取输出，并具备全面的 3.0 版本特性，极大地提升了开发效率。

🚀 快速开始

Claude Command Runner 为开发工作流程带来了革命性的改变，Claude 能够通过它：

• 直接在对话中执行终端命令。
• 以智能的时间安排自动捕获输出。
• 跟踪命令历史和模式。
• 通过可配置的策略确保安全性。

✨ 主要特性

智能自动获取

execute_with_auto_retrieve 命令现在能够智能检测命令类型并调整等待时间：

• 快速命令（如 echo、pwd）：2 - 6 秒。
• 中等命令（如 git、npm）：最长 20 秒。
• 构建命令（如 swift build、make）：最长 77 秒。
• 测试命令：最长 40 秒。

完整功能集

• ✅ 双向通信并自动捕获输出。
• ✅ 针对所有命令类型的渐进式延迟系统。
• ✅ 使用 SQLite 数据库记录命令历史。
• ✅ 可配置的安全策略。
• ✅ 多终端支持（推荐使用 Warp）。
• ✅ 基于历史记录的命令建议。

📦 安装指南

前提条件

• macOS 13.0 或更高版本。
• Swift 6.0+（Xcode 16+）。
• Claude Desktop。
• 支持的终端（强烈推荐 Warp）。

快速安装

1. 克隆并构建项目：

git clone https://github.com/M-Pineapple/claude-command-runner.git
cd claude-command-runner
./build.sh

2. 在 Claude Desktop 的 MCP 设置中添加以下配置：

{
  "claude-command-runner": {
    "command": "/path/to/claude-command-runner/.build/release/claude-command-runner",
    "args": ["--port", "9876"],
    "env": {}
  }
}

3. 重启 Claude Desktop。

💻 使用示例

基础用法

可用工具

1. execute_command - 手动执行命令并获取输出。
2. execute_with_auto_retrieve - 智能自动执行并获取输出 ⭐。
3. get_command_output - 手动获取命令输出。
4. preview_command - 预览命令而不执行。
5. suggest_command - 获取命令建议。

示例工作流

你：“构建我的 Swift 项目”
Claude：[执行：swift build]
[智能等待最长 77 秒]
Claude：“构建成功完成！以下是输出内容...”

📚 详细文档

配置

配置文件位于 ~/.claude-command-runner/config.json：

{
  "terminal": {
    "preferred": "auto",
    "fallbackOrder": ["Warp", "WarpPreview", "iTerm", "Terminal"]
  },
  "security": {
    "blockedCommands": ["rm -rf /", "format"],
    "maxCommandLength": 1000
  },
  "history": {
    "enabled": true,
    "maxEntries": 10000
  }
}

常见问题解答

Q：为什么服务器有时会崩溃？

A：这在早期版本中是个主要问题。v3.0 通过移除有问题的后台任务并实现更安全的渐进式延迟系统，彻底解决了服务器稳定性问题。

Q：自动获取功能会为我的命令等待多长时间？

A：这取决于命令类型：

• 简单命令：6 秒。
• Git/npm 命令：20 秒。
• 构建命令：77 秒。
• 未知命令：30 秒。

Q：我可以在 Terminal.app 或 iTerm2 中使用这个工具吗？

A：可以，任何终端都支持基本的命令执行。但自动输出捕获和高级功能需要使用 Warp Terminal。点击此处免费获取 Warp。

Q：让 Claude 运行命令安全吗？

A：安全！每个命令都需要手动确认（按 Enter 键），并且你可以在配置文件中配置阻止的命令和模式。Claude 必须得到你的明确同意才能执行任何命令。

Q：如果我的构建过程超过 77 秒会怎样？

A：自动获取功能将超时并提供命令 ID。你可以在准备好后使用 get_command_output 和该 ID 来获取结果。

Q：我的命令历史记录存储在哪里？

A：存储在 ~/.claude-command-runner/claude_commands.db 的 SQLite 数据库中。它会记录所有命令、输出、退出代码和执行时间。

Q：我可以为这个项目做出贡献吗？

A：当然可以！你可以 fork 仓库，进行修改并提交 PR。请查看下面的贡献指南。

Q：为什么你强烈推荐 Warp？

A：Warp 提供的 API 支持其他终端无法实现的功能：

• 无需轮询即可自动捕获输出。
• 集成的命令历史记录。
• 现代的异步架构。

故障排除

MCP 无响应

1. 检查服务器是否正在运行：lsof -i :9876。
2. 重启 Claude Desktop。
3. 使用 ./build.sh 重新构建项目。

命令未在终端中显示

1. 确保 Warp/WarpPreview 正在运行。
2. 检查 Claude Desktop 日志中是否有错误。
3. 验证 MCP 配置路径。

自动获取功能不起作用

1. 确保你使用的是 execute_with_auto_retrieve（而不是 execute_command）。
2. 检查命令输出文件是否存在：ls /tmp/claude_output_*.json。
3. 对于长命令，等待超时消息后使用手动获取。

数据库未记录命令

如果命令执行但未保存到数据库：

1. 检查数据库完整性：

sqlite3 ~/.claude-command-runner/claude_commands.db "PRAGMA integrity_check;"

2. 如果看到错误或“missing from index”消息，说明数据库已损坏：

# 备份并删除损坏的数据库
mv ~/.claude-command-runner/claude_commands.db ~/.claude-command-runner/claude_commands.db.backup
# 重启 Claude Desktop - 会自动创建新的数据库

3. 验证数据库是否正常工作：

# 检查命令是否被记录
sqlite3 ~/.claude-command-runner/claude_commands.db "SELECT COUNT(*) FROM commands;"

4. 检查是否有多个服务器实例：

ps aux | grep claude-command-runner | grep -v grep
# 如果看到多个实例，杀死所有实例并重启 Claude Desktop

v3.0 版本包含自动损坏检测和恢复功能，但如果问题仍然存在，手动删除数据库文件将强制重新创建一个干净的数据库。

架构

┌─────────────────┐         ┌──────────────────┐         ┌────────────────┐
│ Claude Desktop  │ ←────→  │ Command Runner   │ ←────→  │ Warp Terminal  │
│                 │  MCP    │ MCP Server       │ Script  │                │
│ • 发送命令      │         │ • 端口 9876      │         │ • 执行命令     │
│ • 自动获取      │         │ • 渐进式延迟     │         │ • 捕获输出     │
│ • 获取输出      │         │ • SQLite 数据库  │         │ • 返回结果     │
└─────────────────┘         └──────────────────┘         └────────────────┘

贡献

我们欢迎贡献！贡献步骤如下：

1. Fork 仓库。
2. 创建功能分支（git checkout -b feature/amazing-feature）。
3. 提交更改（git commit -m 'Add amazing feature'）。
4. 推送到分支（git push origin feature/amazing-feature）。
5. 打开 Pull Request。

开发设置

git clone https://github.com/yourusername/claude-command-runner.git
cd claude-command-runner
swift package resolve
swift build

支持本项目

如果 Claude Command Runner 帮助你优化了开发工作流程，或者通过智能命令执行节省了时间，考虑支持其开发：

你的支持将帮助我：

• 维护和改进 Claude Command Runner，添加新功能。
• 保持项目开源并免费供所有人使用。
• 投入更多时间处理用户请求和修复漏洞。
• 探索新的终端集成和命令智能。

感谢你考虑支持我的工作！🙏

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

由 🍍 用心打造

如果你觉得这个项目有帮助，请给它一个 ⭐ 并尝试使用 Warp 终端！

📊 为什么推荐 Warp 终端？

为了获得最佳体验，我们推荐使用 Warp 终端：

💡 免费获取 Warp：下载 Warp 终端 - 它是免费的，能让 Claude Command Runner 更强大！