Skip to main content
Glama
Capsule Bash Server

Capsule Bash Server

Official
by capsulerun

Capsule Bash MCP

MCP Server

An MCP server that gives your AI agent the ability to run bash commands in a secure, persistent, sandboxed environment.

How It Works

Each session runs inside a WebAssembly sandbox. The sandbox provides:

  • Persistent state: cwd, env vars, and filesystem changes persist across commands within a session

  • Filesystem diff: every run response includes a diff of what changed on disk

  • Isolated memory: each session gets its own address space, no cross-session leakage

  • No host access: the sandbox cannot reach your host filesystem or network

Learn more about Capsule Bash.

Related MCP server: execkit-mcp

Tools

Tool

Description

run

Run a bash command in a sandboxed session. Returns stdout, stderr, exit code, filesystem diff, and current state (cwd + env).

reset

Reset the filesystem and state (cwd, env vars) for a session back to their initial values.

sessions

List all active sessions.

Sessions

Commands within the same session_id share cwd, environment variables, and filesystem state across calls.

Example

Ask your AI agent:

"Write a Python script that averages a list of numbers."

The agent calls run sequentially:

{ "command": "mkdir -p /data && cd /data", "session_id": "custom_session" }
{ "command": "echo 'nums = [x for x in [1, 2, 3, []] if isinstance(x, int)]\nprint(sum(nums) / len(nums))' > avg.py", "session_id": "custom_session" }
{ "command": "python3 avg.py", "session_id": "custom_session" }

Each call returns stdout, stderr, exitCode, a filesystem diff, and the updated state to enrich context and keep trace in conversation history.

Setup

Add to your MCP client configuration (e.g. Claude Desktop, Cursor):

{
  "mcpServers": {
    "bash": {
      "command": "npx",
      "args": ["-y", "@capsule-run/bash-mcp"]
    }
  }
}

Limitations

  • Not all bash commands and options are implemented. Feel free to open an issue if a command is missing or behaves unexpectedly.

Available Tools

3 tools
resetA

Reset a session's filesystem and shell state (cwd, env vars) to their initial values. Useful to start fresh without creating a new session.

Inputs: session_id.

runB

Execute a Bash command in the sandboxed environment

Inputs: command (required), session_id.

sessionsA

List all active session IDs and their current state.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a unique, clear purpose: reset reverts state, run executes commands, and sessions lists active sessions. No ambiguity or overlap exists.

    Naming Consistency5/5

    All tool names are single, imperative verbs (reset, run, sessions) following a consistent, simple pattern.

    Tool Count5/5

    Three tools is well-scoped for a bash sandbox server, covering essential operations without superfluous or missing tools.

    Completeness4/5

    The set covers core actions (run, reset, list sessions) but lacks explicit session creation; likely sessions are created implicitly, leaving a minor gap.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers