进程MCP服务器

MCP（模型上下文协议）服务器和库，提供具有两种执行模式的流程管理功能：

主机模式：通过沙盒直接在主机系统上执行进程 @anthropic-ai/sandbox-runtime
Docker模式：在隔离的Docker容器中执行进程

用作：

🔌 MCP 服务器 -用于Claude Desktop和其他MCP客户端的独立服务器
📦 图书馆 -使用以下命令导入到Node.js应用程序中 createProcessMCP()

该服务器公开了5个MCP工具，用于生成、监视和控制长时间运行的进程，支持交互式TTY会话、stdin/stdout/stderr处理和后台执行。

特性

双执行模式（主机/docker）
TTY支持交互式应用程序（vim、python REPL等）
后台进程执行
自动超时处理
Stdin与转义序列解析的交互
具有可配置限制的输出缓冲
带有清理功能的进程注册表
安全沙盒（主机模式）或容器隔离（docker模式）

安装

作为独立的MCP服务器

git clone 
cd process-mcp
npm install
npm run build

作为项目中的图书馆

npm install process-mcp

或者，如果从本地目录安装：

npm install /path/to/process-mcp

可选依赖关系

对于启用沙盒的主机模式：

ripgrep：沙盒运行时文件系统监控所需

  # macOS
  brew install ripgrep

  # Ubuntu/Debian
  apt install ripgrep

  # Other systems
  # See: https://github.com/BurntSushi/ripgrep#installation

如果未安装ripgrep，服务器将在没有沙盒功能的情况下运行，但进程仍将正常执行。

用法

图书馆使用情况

您可以在自己的Node.js应用程序中将process-mcp用作库：

import { createProcessMCP } from 'process-mcp';

// Create server with host mode
const { server, executor, cleanup } = await createProcessMCP({
  mode: 'host',
  defaults: {
    workdir: '/tmp',
    timeoutMs: 10000,
    maxTimeoutMs: 60000,
  },
});

// Option 1: Use with MCP protocol
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
const transport = new StdioServerTransport();
await server.connect(transport);

// Option 2: Use executor directly (without MCP protocol)
const result = await executor.spawn({
  command: 'echo "Hello World"',
  cwd: '/tmp',
  background: false,
});

if (result.success) {
  console.log(result.value.stdout);
}

// List processes
const processes = executor.listProcesses();

// Get output
const output = executor.getOutput(pid, 100);

// Kill process
await executor.kill(pid, 'SIGTERM');

// Cleanup when done
await cleanup();

Docker模式示例：

const { server, executor, cleanup } = await createProcessMCP({
  mode: 'docker',
  docker: {
    image: 'python:3.11',
    containerName: 'my-container',
    volumeName: 'my-volume',
    useExisting: false,
  },
  defaults: {
    workdir: '/workspace',
    timeoutMs: 10000,
    maxTimeoutMs: 60000,
  },
});

看 examples/ 更多使用示例的目录：

examples/simple-example.js -基本用法
examples/library-usage.ts -包括HTTP服务器集成在内的综合示例

独立服务器

主机模式（默认）

PROCESS_MODE=host npm start

主机模式使用 @anthropic-ai/sandbox-runtime 用于操作系统级沙盒。通过环境变量配置安全限制：

SANDBOX_ALLOWED_DOMAINS：逗号分隔的允许网络域列表（默认值： * 为所有人）
SANDBOX_ALLOW_WRITE：写入访问的其他路径
SANDBOX_DENY_READ：阻止读取的路径
SANDBOX_DENY_WRITE：阻止写入的路径

例子：

PROCESS_MODE=host \
SANDBOX_ALLOWED_DOMAINS="github.com,api.openai.com" \
SANDBOX_DENY_READ="/etc/shadow,/root" \
npm start

Docker模式

PROCESS_MODE=docker npm start

Docker模式创建一个长时间运行的容器，并通过以下方式执行所有进程 docker exec.

重要：Docker模式使用 现有Docker镜像 -默认情况下不需要Dockerfile。如果本地不可用，服务器将从Docker Hub中提取指定的映像。

通过环境变量进行配置：

DOCKER_IMAGE：要使用的Docker镜像（默认值： ubuntu:22.04)
DOCKER_VOLUME：持久性卷名称（默认值： process-mcp-volume)
DOCKER_CONTAINER：容器名称（默认值： process-mcp-main)
DOCKER_USE_EXISTING：使用现有容器而不是创建新容器（默认值： false)

使用不同的图像：

# Python environment
PROCESS_MODE=docker DOCKER_IMAGE="python:3.11" npm start

# Node.js environment
PROCESS_MODE=docker DOCKER_IMAGE="node:20" npm start

# Alpine Linux (smaller)
PROCESS_MODE=docker DOCKER_IMAGE="alpine:latest" npm start

自定义图像（可选）

如果你想要一个带有额外工具的预配置环境，请构建包含的Dockerfile：

# Build custom image
docker build -t process-mcp:custom .

# Use custom image
PROCESS_MODE=docker DOCKER_IMAGE="process-mcp:custom" npm start

自定义图像包括：

Ubuntu 22.04基础版
Python 3、pip、venv
Node.js 20.x
Git、vim、curl、wget
构建工具（gcc、make等）
常用工具（htop、jq、tree）

使用现有容器

如果您已经有一个正在运行的容器，其中包含您所需的环境和卷，您可以直接使用它：

# First, ensure your container is running
docker run -d \
  --name my-dev-container \
  -v my-project:/workspace \
  -w /workspace \
  ubuntu:22.04 \
  tail -f /dev/null

# Then point process-mcp to use it
PROCESS_MODE=docker \
DOCKER_USE_EXISTING=true \
DOCKER_CONTAINER=my-dev-container \
npm start

使用现有容器的好处：

保留现有环境设置（已安装的软件包、配置）
与其他工具/流程共享卷
重用docker compose或其他编排中的容器
在服务器重启之间保持状态

备注：何时 DOCKER_USE_EXISTING=true，服务器将：

无需修改即可使用现有容器
如果停止，请启动它
如果容器不存在，则失败并出错
切勿创建、删除或修改容器（您保持完全控制）

快速开始：参见 example-custom-container.sh 查看创建和使用自定义容器的完整示例。

MCP客户端配置

要将此服务器与MCP客户端（如Claude Desktop）一起使用，请将其添加到MCP配置文件中：

{
  "mcpServers": {
    "process": {
      "command": "node",
      "args": ["/absolute/path/to/process-mcp/dist/index.js"],
      "env": {
        "PROCESS_MODE": "host"
      }
    }
  }
}

看 mcp-config-example.json 更多配置示例，包括Docker模式。

常见的MCP客户端配置位置：

克劳德桌面（macOS）： ~/Library/Application Support/Claude/claude_desktop_config.json
克劳德桌面（Windows）： %APPDATA%\Claude\claude_desktop_config.json

库API

主要出口

`createProcessMCP(config: ProcessMcpConfig): Promise

创建并初始化Process MCP服务器。

退货：

{
  server: Server;        // MCP server instance
  executor: ProcessExecutor; // Process executor
  cleanup: () => Promise; // Cleanup function
}

配置类型

interface ProcessMcpConfig {
  mode: 'host' | 'docker';

  // Sandbox config (host mode only)
  sandbox?: {
    network: {
      allowedDomains: string[];
      deniedDomains: string[];
    };
    filesystem: {
      allowWrite: string[];
      denyRead: string[];
      denyWrite: string[];
    };
  };

  // Docker config (docker mode only)
  docker?: {
    image: string;
    containerName: string;
    volumeName: string;
    useExisting: boolean;
  };

  // Default settings
  defaults: {
    workdir: string;
    timeoutMs: number;
    maxTimeoutMs: number;
  };
}

执行器方法

interface ProcessExecutor {
  // Spawn a process
  spawn(options: SpawnOptions): Promise>;

  // Send input to TTY process
  stdin(pid: string, input: string): Promise>;

  // Get process by PID
  getProcess(pid: string): Result
;

  // List all processes
  listProcesses(): ProcessInfo[];

  // Get process output
  getOutput(pid: string, lines?: number): Result;

  // Kill process
  kill(pid: string, signal?: string): Promise>;

  // Cleanup
  cleanup(): Promise;
}

其他出口

// Load config from environment
import { loadConfig } from 'process-mcp/config';

// Executor implementations
import { HostExecutor, DockerExecutor } from 'process-mcp';

// Types
import type {
  ProcessMcpConfig,
  ProcessExecutor,
  Process,
  SpawnOptions,
  ProcessInfo,
  SpawnResult,
  Result,
} from 'process-mcp';

// Constants
import {
  DEFAULT_TIMEOUT_MS,  // 10000
  MAX_TIMEOUT_MS,      // 60000
  OUTPUT_TRUNCATE,     // 8196
  TERMINAL_COLS,       // 120
  TERMINAL_ROWS,       // 30
} from 'process-mcp';

MCP工具

1.产卵

执行带有可选超时的命令。超过超时的进程会自动移到后台。

参数：

command （string，必填）：要执行的命令
cwd （字符串，可选）：工作目录（默认： /home/agent)
env （对象，可选）：环境变量
tty （布尔值，可选）：为交互式应用程序启用TTY模式
background （布尔值，可选）：在后台运行（绕过超时）
timeoutMs （数字，可选）：超时时间（毫秒）（默认值：10000，最大值：60000）

退货：

pid：进程ID
status：“正在运行”或“已终止”
exitCode：退出代码（如果终止）
stdout：标准输出（截断为8196个字符）
stderr：Stderr输出（截断为8196个字符）

例子：

{
  "command": "python -c 'print(\"hello\")'",
  "tty": false,
  "timeoutMs": 5000
}

2.ps

列出所有正在运行和最近终止的进程。

退货： 流程信息对象数组，包含：

pid：进程ID
command：已执行的命令
status：“正在运行”或“已终止”
exitCode：退出代码（如果终止）
cwd：工作目录
tty：是否启用TTY模式
createdAt：创建时间戳

3.stdin

将输入发送到交互式进程（仅限TTY模式）。

参数：

id （字符串，必填）：进程ID
input （字符串，必填）：要发送的输入

逃生顺序：

\n：新线
\r：回程
\t：选项卡
\xHH：十六进制字节（例如。， \x03 对于Ctrl-C）
\uHHHH：Unicode字符

例子：

{
  "id": "host-1",
  "input": "print('test')\\n"
}

4.标准输出

查看流程输出。返回stdout和stderr（或TTY进程的终端缓冲区）。

参数：

id （字符串，必填）：进程ID
lines （number，可选）：要检索的行数（默认值：100）

退货：

stdout：标准输出（最后N行）
stderr：Stderr输出（最后N行）

5.杀人

用信号终止进程。

参数：

id （字符串，必填）：进程ID
signal （字符串，可选）：要发送的信号（默认值： SIGTERM)

常见信号：

SIGTERM：优雅的终止
SIGKILL：强制击杀
SIGINT：中断（Ctrl-C）

建筑

MCP Server (5 tools: spawn, ps, stdin, stdout, kill)
    ↓
Mode Selection (ENV: PROCESS_MODE=host|docker)
    ↓
ProcessExecutor Interface
    ↓
Host Mode              Docker Mode
(child_process,        (dockerode,
 @anthropic-ai/        single shared
 sandbox-runtime)      container)

发展

# Build
npm run build

# Type check
npm run typecheck

# Run in development (CLI mode)
npm run dev

# Test library functionality
node examples/test-library.js

# Run simple example
node examples/simple-example.js

# Verify installation
bash verify.sh

打包发布

要将其发布到npm或将其用作本地依赖项：

# Build the package
npm run build

# Publish to npm (requires npm account)
npm publish

# Or install locally in another project
cd /path/to/your-project
npm install /path/to/process-mcp

然后在您的项目中使用：

import { createProcessMCP } from 'process-mcp';

Docker模式实现细节

不需要Dockerfile -使用现有的Docker镜像（默认ubuntu:22.04）
单个长时间运行的容器(tail -f /dev/null)
每个进程都是通过 docker exec
容器配置：

- 512MB RAM限制 - 1个vCPU - 4096 PID限制 - 非特权模式 - Tmpfs /tmp 和 /var/tmp （100MB，无需执行）

工作目录的卷持久性(process-mcp-volume:/home/agent)
自动容器重用（重新启动现有容器）
服务器关闭时自动清理
通过命令包装提取PID： echo "PID:$$" >&2 && command

主机模式实施详细信息

用途 @anthropic-ai/sandbox-runtime 出于安全考虑
通过以下方式进行产卵过程 child_process.spawn()
TTY通过管道和 @xterm/headless 终端
可配置的文件系统和网络限制
所有命令的自动沙盒

安全考虑

主机模式

带有沙盒限制的命令
通过allowlists/denylists控制文件系统访问
按域过滤网络访问
进程以最小权限运行

Docker模式

容器无特权运行
实施资源限制
无新增功能
带有noexec的Tmpfs用于临时目录

项目状态

服务器已按计划全面实施：

✅ 具有可选沙盒的主机模式
✅ 容器隔离的Docker模式
✅ 5个MCP工具（spawn、ps、stdin、stdout、kill）
✅ TTY支持交互式应用程序
✅ 后台进程执行
✅ 超时处理
✅ 带有清理功能的进程注册表
✅ 全面的错误处理

验证

运行验证脚本以确保一切正常：

bash verify.sh

许可证

ISC

Process MCP

快速接入

详细介绍

进程MCP服务器

特性

安装

作为独立的MCP服务器

作为项目中的图书馆

可选依赖关系

用法

图书馆使用情况

独立服务器

主机模式（默认）

Docker模式

MCP客户端配置

库API

主要出口

`createProcessMCP(config: ProcessMcpConfig): Promise

配置类型

执行器方法

其他出口

MCP工具

1.产卵

2.ps

3.stdin

4.标准输出

5.杀人

建筑

发展

打包发布

Docker模式实现细节

主机模式实施详细信息

安全考虑

主机模式

Docker模式

项目状态

验证

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP