Bun Runner MCP

包子跑者mcp

一种MCP（模型上下文协议）服务器，在具有基于权限的安全控制的沙盒Bun环境中执行Types/JavaScript代码。

特性

• 沙盒执行：在隔离的环境中运行Types/JavaScript代码
• 权限系统：对HTTP请求、文件访问和环境变量进行细粒度控制
• 代码片段：通过依赖关系解析在会话之间保存和重用代码片段
• Web管理UI：用于管理环境变量和查看代码段的基于浏览器的界面
• 两种执行模式:

- 预加载 （默认）：使用Bun的预加载功能进行运行时沙盒 - 容器：使用Apple容器进行VM级隔离（macOS 26+）

• HTTP 代理：所有网络请求都通过权限检查代理进行路由

快速开始

安装

git clone https://github.com/timoconnellaus/bun-runner-mcp.git
cd bun-runner-mcp
bun install

Claude桌面配置

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

标准模式（预加载沙盒）：

{
  "mcpServers": {
    "bun-runner": {
      "command": "bun",
      "args": ["run", "/path/to/bun-runner-mcp/src/mcp/server.ts"]
    }
  }
}

容器模式（Apple容器-建议用于不受信任的代码）：

{
  "mcpServers": {
    "bun-runner": {
      "command": "bun",
      "args": ["run", "/path/to/bun-runner-mcp/src/mcp/server.ts"],
      "env": {
        "EXECUTION_MODE": "container"
      }
    }
  }
}

注： 容器模式需要安装了Apple Containers的macOS 26（Tahoe）或更高版本。

手动运行

# Standard mode
bun run start

# Container mode
EXECUTION_MODE=container bun run start

# Development with watch
bun run dev

MCP工具

run_code

在沙盒中执行Types/JavaScript代码。

{
  "code": "console.log('Hello, world!')",
  "timeout": 30000
}

grant_permission

授予当前会话的权限。

HTTP权限：

{
  "permission": {
    "type": "http",
    "host": "api.example.com",
    "description": "Access example API"
  }
}

文件权限：

{
  "permission": {
    "type": "file",
    "path": "/tmp/data/*",
    "operations": ["read", "write"],
    "description": "Access temp files"
  }
}

环境变量权限：

{
  "permission": {
    "type": "env",
    "variables": ["API_KEY", "SECRET_*"],
    "description": "Access API keys"
  }
}

list_permissions

列出当前授予的所有权限。

revoke_permission

撤销之前授予的权限。

save_snippet

保存可重用的代码段。代码段必须包含JSDoc @description 标签。

{
  "name": "fetch-json",
  "code": "/** @description Fetches JSON from a URL */\nexport async function fetchJson(url: string) {\n  const res = await fetch(url);\n  return res.json();\n}"
}

list_snippets

列出所有保存的片段及其名称和描述。

get_snippet

获取已保存代码段的完整代码和元数据。

delete_snippet

删除已保存的代码段。

list_env_vars

列出可用的环境变量名称（为了安全起见，值被隐藏）。

get_web_ui_url

获取web管理界面的URL。AI可以使用此功能将用户引导到浏览器UI。

代码片段

代码段是可重用的代码块，在会话中持久存在。它们存储在 ~/.bun-runner-mcp/snippets/.

在代码中使用代码段

使用 @use-snippet 指令：

// @use-snippet: fetch-json
// @use-snippet: format-date

const data = await fetchJson('https://api.example.com/data');
console.log(formatDate(data.timestamp));

代码段代码在执行前会自动内联。代码段可以依赖于其他代码段，并检测到循环依赖关系。

代码段要求

• 必须包含JSDoc注释 @description 标签
• 名称必须是带连字符/下划线的字母数字
• 是否应导出函数以供重用

环境变量

环境变量可以配置为在执行的代码中使用：

配置源

1. MCP配置：传递变量 BUN_ MCP配置中的前缀：

   {
     "env": {
       "BUN_API_KEY": "your-api-key",
       "BUN_DEBUG": "true"
     }
   }

这 BUN_ 当在代码中访问时，前缀被剥离（例如。， process.env.API_KEY).

1. Env文件：创建 ~/.bun-runner-mcp/.bun-runner-env:

   API_KEY=your-api-key
   DATABASE_URL=postgres://localhost/db

文件变量优先于MCP配置变量。

热重新加载

监视env文件是否有更改。修改后，变量会自动重新加载（如果处于容器模式，容器会重新启动）。

Web管理UI

基于浏览器的界面可在 http://localhost:9999 用于：

• 环境变量：添加、编辑和删除环境变量
• 代码片段：查看已保存的代码段及其代码

当服务器开始使用Bun的原生bundler时，web UI会自动构建。

执行模式

预加载模式（默认）

使用Bun的预加载功能来拦截和沙盒网络请求。所有HTTP请求都通过强制权限的本地代理服务器（端口9999）路由。

容器模式（苹果容器）

为了加强隔离，请使用提供VM级隔离的Apple Containers。这是不受信任的代码执行的推荐模式。

需求

• macOS 26（Tahoe） 或以后
• 苹果容器CLI(container 命令）已安装
• 用于初始图像提取的互联网连接

运作原理

1. 延迟初始化：容器是在第一次执行代码时创建的，而不是在启动时创建的
2. 会话保持：会话中的所有执行都重用同一个容器
3. 自动清理：MCP服务器退出时，容器会自动停止
4. 图像管理：用途 oven/bun:alpine 来自Docker Hub，首次使用时自动拉取

集装箱规格

特性

• VM级隔离：代码在完全隔离的虚拟机中运行
• 独立文件系统：无法访问主机文件系统
• 网络隔离：网络访问由容器运行时控制
• 套餐支持：npm包通过Bun自动安装
• TypeScript支持：通过tsserver执行带有类型检查的完整TypeScript

验证容器CLI

检查Apple容器是否可用：

container --version

列出可用图像：

container image list

故障排除

未找到容器CLI：

• 确保您运行的是macOS 26（Tahoe）或更高版本
• 这 container CLI应可在 /usr/bin/container

图像拉取失败：

• 检查您的互联网连接
• 验证Docker Hub是否可访问
• 手动尝试： container image pull docker.io/oven/bun:alpine

容器无法启动：

• 检查系统资源（内存、磁盘空间）
• 在stderr输出中查找错误消息
• 确保没有冲突的容器正在运行

建筑

┌─────────────────┐     ┌──────────────────┐
│   MCP Client    │────▶│   MCP Server     │
│  (Claude, etc)  │     │  (stdio transport)│
└─────────────────┘     └────────┬─────────┘
                                 │
                    ┌────────────┴────────────┐
                    │                         │
              ┌─────▼─────┐           ┌───────▼───────┐
              │  Preload  │           │   Container   │
              │  Sandbox  │           │    (Apple)    │
              └─────┬─────┘           └───────────────┘
                    │
              ┌─────▼─────┐
              │HTTP Proxy │
              │ (port 9999)│
              └───────────┘

许可证

麻省理工学院