mcpbash

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<{ url: string; close(): Promise<void> }> {
  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");
      });
      req.on("end", () => {
        const { input } = JSON.parse(body) as { input?: { q?: string } };
        const query = input?.q ?? "";

        res.setHeader("content-type", "application/json");
        res.end(
          JSON.stringify({
            result: {
              query,
              repos: [
                `${query}-api`,
                `${query}-web`,
                `${query}-worker`,
              ],
            },
          })
        );
      });
    });

    server.listen(0, "127.0.0.1", () => {
      const address = server.address();
      if (!address || typeof address === "string") {
        throw new Error("failed to start tool server");
      }

      resolve({
        url: `http://127.0.0.1:${address.port}`,
        close: () =>
          new Promise<void>((done, reject) => {
            server.close((error) => {
              if (error) reject(error);
              else done();
            });
          }),
      });
    });
  });
}

const toolServer = await startToolServer();

try {
  const sandbox = await createSandbox({
    filesystem: { mode: "memory" },
    network: {
      allow: ["127.0.0.1"],
    },
    commands: {
      "repos.search": mcp({
        server: toolServer.url,
        tool: "search_repositories",
        input: { q: "$1" },
      }),
    },
  });

  const result = await sandbox.run('repos.search "billing"');
  console.log(result.stdout);
  // {
  //   "query": "billing",
  //   "repos": ["billing-api", "billing-web", "billing-worker"]
  // }

  await sandbox.dispose();
} finally {
  await toolServer.close();
}

See also: packages/mcpbash/examples/mcp-demo.ts

Wrap a local CLI

import { cli, createSandbox } from "mcpbash";

const sandbox = await createSandbox({
  commands: {
    upper: cli({
      command: process.execPath,
      args: [
        "-e",
        "process.stdout.write((process.argv[1] ?? '').toUpperCase())",
        "$1",
      ],
    }),
  },
});

console.log((await sandbox.run('upper "hello"')).stdout); // HELLO

Work in a writable directory with git

import { createSandbox } from "mcpbash";

const sandbox = await createSandbox({
  filesystem: {
    mode: "readwrite",
    root: "./workspace",
  },
  integrations: {
    git: true,
  },
});

await sandbox.run("git init -q");
await sandbox.fs.write("README.md", "# demo\n");

const status = await sandbox.git?.status(["--short"]);
console.log(status?.stdout);

API at a glance

import { createSandbox, mcp, fn, cli, provider, secret } from "mcpbash";

• createSandbox(...) creates a sandbox
• mcp(...) maps an MCP tool to a command
• fn(...) maps a TypeScript handler to a command
• cli(...) wraps a local binary
• provider(...) is an alias for cli(...) for external runtimes
• secret.env("NAME") resolves a secret at runtime
• sandbox.run(...) executes a command
• sandbox.fs exposes read, write, list, and exists
• sandbox.git exposes status, diff, and log when git is enabled

Filesystem modes

• memory: isolated in-memory sandbox
• readonly: overlay an existing directory without writes
• readwrite: back the sandbox with a real directory

Examples in this repo

• packages/mcpbash/examples/mixed-demo.ts
• packages/mcpbash/examples/mcp-demo.ts
• packages/mcpbash/examples/git-demo.ts
• packages/mcpbash/examples/benchmark.ts

Run them:

pnpm install
pnpm --filter mcpbash demo:mixed
pnpm --filter mcpbash demo:mcp
pnpm --filter mcpbash demo:git
pnpm --filter mcpbash bench

Advanced usage

See ADVANCED.md for:

• filesystem allow/deny rules
• secrets
• network policy
• MCP auth and OAuth patterns
• provider examples with Daytona, Upstash Box, and Docker
• current limitations

Performance

Local benchmark on April 9, 2026, on an Apple M4 Pro with Bun 1.3.5:

The important takeaway is category-level: mcpbash stays on the local fast path. It does not provision a VM, container, or remote session just to dispatch a mapped command, so startup and dispatch stay in the low-millisecond range.

Run the benchmark locally:

pnpm --filter mcpbash bench

Development

pnpm install
pnpm --filter mcpbash typecheck
pnpm --filter mcpbash build
pnpm --filter mcpbash test