MCP Sidecar

mcp-sidecar

一款轻量、跨平台的 MCP 服务，用于管理后台进程。使用 Go 构建，可打包为单个二进制文件，且无需运行时依赖。

为什么需要它？

AI 编码 Agent（Claude Code、Gemini CLI、Cursor 等）无法在继续交互的同时运行长时间存续的进程。常见的受影响工作流包括：

• 启动 API 服务，等待其就绪，然后对其发送 HTTP 请求
• 在编辑代码的同时以监视模式运行构建
• 启动数据库，为其填充数据，运行测试，然后关闭数据库

mcp-sidecar 通过 stdio 传输将进程生命周期管理作为 MCP 工具提供，从而解决了这个问题。

功能

• 跨平台——使用同一套代码库支持 Windows、Linux 和 macOS
• 零依赖——单个 Go 二进制文件，无需运行时
• 精简易用——6 个工具，没有不必要的复杂性
• 可靠清理——服务退出时会终止所有子进程；已退出的进程会在可配置的 TTL 后自动移除
• 输出控制——通过每个请求的 maxBytes 和全局 SIDECAR_MAX_OUTPUT_SIZE 限制返回给大模型的输出
• 命令安全——可选的可执行文件允许列表、禁止模式和审计日志

安装

快速设置（任意 Agent）

将 mcp-sidecar 安装到任何受支持的编码 Agent 中的最快方式：

# Interactive -- detects installed agents and lets you pick
npx add-mcp mcp-sidecar

# Install to a specific agent
npx add-mcp mcp-sidecar -a claude-code
npx add-mcp mcp-sidecar -a cursor
npx add-mcp mcp-sidecar -a vscode

# Install to all detected agents
npx add-mcp mcp-sidecar --all

支持的 Agent：Claude Code、Codex、Cursor、VS Code、Gemini CLI、OpenCode、Zed、Goose、Cline 等。完整列表请参阅 add-mcp。

手动配置

Claude Code：

claude mcp add sidecar -- npx -y mcp-sidecar

opencode（~/.config/opencode/opencode.json）：

{
  "mcp": {
    "sidecar": {
      "type": "local",
      "command": ["npx", "-y", "mcp-sidecar"],
      "enabled": true
    }
  }
}

通用配置（mcp.json）：

{
  "mcpServers": {
    "sidecar": {
      "command": "npx",
      "args": ["-y", "mcp-sidecar"]
    }
  }
}

从源代码构建

go install github.com/lsequeiraa/mcp-sidecar@latest

也可从 GitHub Releases 下载预构建的二进制文件，适用于 windows/amd64、linux/amd64、darwin/arm64 和 darwin/amd64。

工具

工具	说明	参数	返回值
start	启动后台进程	command、name?、cwd?、env?	{ id, name, pid }
stop	终止进程（先尝试正常终止，再强制终止）	id	{ id, exitCode, uptime }
list	列出所有受管理的进程	--	[{ id, name, pid, state, uptime }]
output	获取缓冲的 stdout/stderr	id、tail?、maxBytes?	{ stdout, stderr, uptime }
send	向进程的 stdin 写入内容	id、input	{ ok }
status	获取单个进程的详细状态	id	{ id, name, pid, state, exitCode, uptime, outputSize }

uptime 字段表示实际运行时长：对于正在运行的进程，它表示从启动到现在的时间；对于已退出的进程，它表示进程存活的时长（而非从启动到现在的时间）。

output 工具的 maxBytes 参数限制 stdout 和 stderr 合计的总字节数。如果同时提供 tail 和 maxBytes，则先由 tail 选择行，再由 maxBytes 限制结果的字节数。输出超出限制时，会保留最新内容，并优先保留 stderr。截断时会保留完整行。如果输出被截断，响应会包含 "truncated": true 和表示原始大小的 "totalBytes"。

进程状态

状态	含义
running	进程正在运行
exited	进程正常终止
failed	进程以非零退出码终止
killed	进程通过 stop 工具停止

工作流示例

一个典型会话：Agent 启动 API 服务，等待服务就绪，进行测试，然后关闭服务：

1. start  { command: "dotnet run --project MyApi", name: "api" }
   → { id: "sc-a1b2c3", name: "api", pid: 12345 }

2. output { id: "sc-a1b2c3", tail: 5 }
   → { stdout: "Now listening on: http://localhost:5000", stderr: "", uptime: "3s" }

3. (agent runs curl http://localhost:5000/health using its own shell)

4. output { id: "sc-a1b2c3", tail: 20 }
   → { stdout: "...request logs...", stderr: "", uptime: "15s" }

5. stop   { id: "sc-a1b2c3" }
   → { id: "sc-a1b2c3", exitCode: -1, uptime: "18s" }

Agent 使用原生 Shell 执行短时命令（curl、构建工具等），使用 mcp-sidecar 管理需要在多次工具调用之间保持运行的进程。

配置

所有配置均通过环境变量进行（均为可选）：

变量	默认值	描述
SIDECAR_MAX_PROCESSES	10	最大并发进程数
SIDECAR_BUFFER_SIZE	1048576 (1MB)	每个进程的输出缓冲区大小（字节）
SIDECAR_KILL_TIMEOUT	5000	SIGTERM 和 SIGKILL 之间的等待毫秒数
SIDECAR_CLEANUP_AFTER	1800 (30 min)	进程退出后自动移除前的秒数。0 = 禁用
SIDECAR_MAX_OUTPUT_SIZE	0 (unlimited)	output 工具返回的全局字节数上限。0 = 无限制
SIDECAR_ALLOWED_EXECUTABLES	--	以逗号分隔的可执行文件允许列表（启用安全模式）
SIDECAR_BLOCKED_PATTERNS	--	以逗号分隔的正则表达式模式，用于拒绝命令
SIDECAR_AUDIT_LOG	--	审计日志目录，或 true（当前工作目录）/ temp（操作系统临时目录）

自动清理说明： 启用 SIDECAR_CLEANUP_AFTER 时（默认启用），进程退出并经过 TTL 后，会从管理器中移除。移除后，对该进程 ID 调用 output、status 或 stop 将返回“未找到”。请在 TTL 时限内获取所需输出（默认 30 分钟）。

安全性

设置 SIDECAR_ALLOWED_EXECUTABLES 后，mcp-sidecar 将从 shell 模式切换到安全模式：

	Shell 模式（默认）	安全模式
执行方式	通过 sh -c / cmd /C	直接执行（不使用 shell）
允许列表	无	仅允许运行列出的可执行文件
元字符	允许（由 shell 解释）	拒绝（|、&、;、>、<、$、`、(、)）
阻止模式	无	与完整命令匹配的正则表达式模式
审计日志	无	可选的 JSONL 日志，记录所有启动/停止/拦截事件

引号内的元字符允许使用——grep "error|warning" file.txt 可以正常运行，因为 | 位于双引号内，不会被 shell 解释。

反斜杠（\）不会被视为元字符，这是有意为之，因此像 C:\Users\me\app.exe 这样的 Windows 路径无需转义即可使用。

配置示例

Claude Desktop / Cursor（mcp.json）：

{
  "mcpServers": {
    "sidecar": {
      "command": "npx",
      "args": ["-y", "mcp-sidecar"],
      "env": {
        "SIDECAR_ALLOWED_EXECUTABLES": "dotnet,npm,node,git,python",
        "SIDECAR_BLOCKED_PATTERNS": "rm\\s+-rf,--force,--no-verify",
        "SIDECAR_AUDIT_LOG": "./logs"
      }
    }
  }
}

Claude Code：

claude mcp add sidecar \
  -e SIDECAR_ALLOWED_EXECUTABLES=dotnet,npm,node,git,python \
  -e SIDECAR_BLOCKED_PATTERNS="rm\\s+-rf,--force,--no-verify" \
  -e SIDECAR_AUDIT_LOG=true \
  -- npx -y mcp-sidecar

审计日志格式

审计日志始终写入配置目录中的 sidecar-audit.jsonl 文件。SIDECAR_AUDIT_LOG 变量用于控制日志位置：

值	日志文件位置
true	./sidecar-audit.jsonl（当前工作目录）
temp	<OS temp dir>/sidecar-audit.jsonl
./logs	./logs/sidecar-audit.jsonl（自动创建目录）

每行都是一个 JSON 对象，包含以下三种事件类型之一：

{"ts":"2025-03-12T10:00:00Z","event":"start","id":"abc123","command":"dotnet run","cwd":"/app"}
{"ts":"2025-03-12T10:00:05Z","event":"stop","id":"abc123","exit_code":0,"duration":"5s"}
{"ts":"2025-03-12T10:00:06Z","event":"blocked","command":"rm -rf /","reason":"executable \"rm\" is not in allowed list"}

可执行文件匹配

允许列表支持三种匹配模式：

允许列表条目	匹配对象
dotnet	任意位置的 dotnet（按基本名称匹配）
./build.sh	仅 ./build.sh（精确匹配）
/usr/bin/python3	仅 /usr/bin/python3，或通过 PATH 解析到的任意 python3

分发

渠道	用法
npm	npx -y mcp-sidecar（通过 @mcp-sidecar/* 可选包提供平台二进制文件）
GitHub Releases	每个版本均附带预构建的二进制文件
MCP Registry	io.github.lsequeiraa/mcp-sidecar

许可证

MIT