home / mcp / chuk mcp vfs mcp server

Chuk MCP VFS MCP Server

Provides a unified, asynchronous virtual filesystem workspace server with session, user, and sandbox scopes for AI agents.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "ibm-chuk-mcp-vfs": {
      "command": "chuk-mcp-vfs",
      "args": [
        "--transport",
        "stdio"
      ]
    }
  }
}

You run a Chuk MCP VFS server to create and manage virtual filesystem workspaces that are automatically scoped by session, user, or sandbox. This enables AI agents to read, write, organize, and checkpoint files across isolated environments using a unified namespace architecture.

How to use

You interact with the MCP server through a client that can request workspace management and VFS operations. Create workspaces, perform file operations, navigate the virtual filesystem, and manage checkpoints. All actions are modeled with strongly typed requests and responses, and scopes ensure the right level of persistence and sharing for each workspace.

How to install

Prerequisites: Ensure Python is installed and available on your system. You may also want a modern terminal and Python’s package manager.

# Basic installation
pip install chuk-mcp-vfs

# With FUSE mounting support (Linux/macOS)
pip install chuk-mcp-vfs[mount]

# Development
pip install -e .[dev]

Additional setup notes

You can run the MCP server in two transport modes. The default is STDIO, which is suitable for Claude Desktop, or SSE for HTTP streaming.

To run in STDIO mode, execute the server binary with no additional transport flag. To explicitly specify STDIO, include the transport flag.

If you need HTTP/streaming access, run the server with the SSE transport and bind to your preferred host and port.

Available tools

workspace_create

Create a new virtual workspace with a specified storage provider and scope (SESSION, USER, SANDBOX).

workspace_destroy

Delete an existing workspace and release resources.

workspace_list

List all available workspaces.

workspace_switch

Switch the active workspace in your session.

workspace_info

Fetch details about a workspace, including its scope and storage provider.

read

Read file contents from the current working directory within a workspace.

write

Write data to a file at a given path within the active workspace.

ls

List the contents of a directory in the VFS.

tree

Show a hierarchical tree view of a directory.

mkdir

Create a new directory at a specified path.

rm

Remove a file or directory, with an option for recursive deletion.

mv

Move or rename a file or directory.

cp

Copy a file or directory, with an option for recursive copy.

cd

Change the current working directory within the workspace.

pwd

Print the current working directory.

find

Find files matching a glob pattern within the workspace.

grep

Search for text patterns inside file contents.

checkpoint_create

Create a checkpoint capturing the current filesystem state for a workspace.

checkpoint_restore

Restore a workspace to a previously saved checkpoint.

checkpoint_list

List all checkpoints for a workspace.

checkpoint_delete

Delete a specific checkpoint to free resources.