1mcpSAFE

Build tiny sandboxes from MCP tools, TypeScript functions, CLIs, and just-bash.

mcpbash gives you a small shell-first sandbox object. Instead of provisioning a VM or container, you map capabilities into commands and run them through a controlled runtime.

Install

pnpm add mcpbash
# or
npm install mcpbash

Why use it?

• Map MCP tools to shell commands
• Map TypeScript functions to shell commands
• Wrap existing binaries
• Choose an in-memory, read-only, or read-write filesystem
• Opt into git support when you need it
• Control outbound MCP access with a simple network policy
• Resolve secrets at runtime instead of hardcoding them

Quick start

This example creates one command, slugify, and runs it inside the sandbox.

import { createSandbox, fn } from "mcpbash";

const sandbox = await createSandbox({
filesystem: { mode: "memory" },
commands: {
slugify: fn({
input: { text: "$1" },
handler: ({ text }: { text: string }) =>
text.toLowerCase().replace(/\s+/g, "-"),
}),
},
});

const result = await sandbox.run('slugify "Hello World"');

console.log(result.stdout); // hello-world
console.log(result.exitCode); // 0

await sandbox.dispose();

Common patterns

Run a real MCP-backed command

This example is fully runnable. It starts a tiny local HTTP server that behaves like an MCP tool endpoint, maps that tool into the sandbox as repos.search, and calls it like a shell command.

import http from "node:http";
import { createSandbox, mcp } from "mcpbash";

async function startToolServer(): Promise }> {
return new Promise((resolve) => {
const server = http.createServer((req, res) => {
if (req.method !== "POST" || req.url !== "/tools/search_repositories") {
res.statusCode = 404;
res.end("not found");
return;
}

let body = "";
req.on("data", (chunk) => {
body += chunk.toString("utf8"