内容
# orbstack-mcp
MCP（模型上下文协议）服务器，适用于 [OrbStack](https://orbstack.dev/)，使 Claude Code 和 Cursor 等 AI 助手可以直接操作、监控和调试 Docker 容器。
使用 Go 语言构建，基于官方 [MCP Go SDK](https://github.com/modelcontextprotocol/go-sdk)。
## 功能特点
- **12 种工具**，用于全面的容器管理
- 与 OrbStack 的 Docker 运行时无缝集成
- 支持 Compose 项目感知（分组、项目级操作）
- 安全执行：无 shell 注入，命令通过 `exec.CommandContext` 运行
- 标准输入输出传输，与 MCP 客户端无缝集成
## 安装
```bash
go install github.com/otsukatsuka/orbstack-mcp@latest
```
或从源代码构建：
```bash
git clone https://github.com/otsukatsuka/orbstack-mcp.git
cd orbstack-mcp
go build -o orbstack-mcp .
```
## 配置
### Claude Code
将以下内容添加到您的 Claude Code MCP 设置（`~/.claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"orbstack": {
"command": "orbstack-mcp"
}
}
}
```
或如果从源代码构建：
```json
{
"mcpServers": {
"orbstack": {
"command": "/path/to/orbstack-mcp"
}
}
}
```
### Cursor
将以下内容添加到您的 Cursor MCP 设置（`.cursor/mcp.json`）：
```json
{
"mcpServers": {
"orbstack": {
"command": "orbstack-mcp"
}
}
}
```
## 工具列表
### 核心工具
| 工具 | 描述 |
|------|-------------|
| `list_containers` | 列出容器，按 Compose 项目分组。支持按项目名称过滤。 |
| `get_logs` | 获取容器日志，支持 tail/since/until/timestamps 选项。 |
| `search_logs` | 使用正则表达式搜索日志。支持上下文行（类似 `grep -C`）。 |
| `compose_logs` | 获取 Compose 项目中所有服务的合并日志，服务名称前缀。 |
### 调试工具
| 工具 | 描述 |
|------|-------------|
| `container_exec` | 在容器内执行命令，通过 `sh -c`（支持管道/重定向）。 |
| `restart_service` | 重启容器，支持可配置超时。 |
| `container_stats` | 获取 CPU/内存/网络/块 I/O 统计信息快照。 |
### 检查和故障排查工具
| 工具 | 描述 |
|------|-------------|
| `container_inspect` | 获取详细的容器信息，支持分区过滤（env/ports/volumes/network/all）。 |
| `container_health` | 获取健康检查配置和最近的检查结果。 |
| `log_diff` | 比较两个时间段的日志，进行回归调试。 |
### Compose 和事件工具
| 工具 | 描述 |
|------|-------------|
| `compose_up` | 启动 Compose 项目（自动从容器发现工作目录）。 |
| `compose_down` | 停止 Compose 项目，支持可选的卷删除。 |
| `container_events` | 获取容器事件历史（start/stop/die/restart/OOM）。 |
## 开发
### 前置条件
- Go 1.24+
- Docker（通过 OrbStack）
### 运行测试
```bash
go test ./... -v
```
### 构建
```bash
go build ./...
```
## 许可证
Apache 2.0 - 请参阅 [LICENSE](LICENSE)。
