mcp-virtual-fs

You can use this MCP server to give AI agents a PostgreSQL-backed virtual filesystem that persists across restarts and scales across deployments. It decouples storage from the agent runtime, providing session-isolated namespaces, cross-session stores for long-term memory, standard file operations, and optional row-level security.

How to use

You interact with the virtual filesystem through an MCP client. Create, read, write, and manage files and directories inside a per-session namespace or within named persistent stores that survive across sessions. Use common POSIX-style operations to work with files, and opt in to cross-session stores when you need memory that extends beyond a single session.

Key usage patterns include:

• Write a file to a path and have missing directories created automatically.

If you want to resume a specific session after a restart, provide a deterministic session identifier through your client configuration so previously created namespaces and stores remain accessible.

How to install

Follow these concrete steps to set up a working environment with PostgreSQL and the MCP server client that connects to it.

Prerequisites you need before starting:

Step-by-step setup:

# 1. Start PostgreSQL in a container (example)
docker run -d --name vfs-postgres \
  -e POSTGRES_DB=vfs \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:16-alpine

# 2. Install and run the MCP client that provides the virtual file system
# The client is run via npx and exposes the vfs as an MCP server

Additional configuration and usage notes

Configuration is focused on the database connection and optional isolation. The critical pieces shown here are the PostgreSQL connection URL and an option to auto-create tables on startup. You can also enable row-level security for stronger isolation between sessions.

Typical configuration you will use in your MCP client setup includes the database URL and a flag to auto-initialize the database schema on first run.

{
  "mcpServers": {
    "virtual-fs": {
      "command": "npx",
      "args": ["-y", "mcp-virtual-fs"],
      "env": {
        "DATABASE_URL": "postgresql://postgres:postgres@localhost:5432/vfs",
        "VFS_AUTO_INIT": "true"
      }
    }
  }
}

Security and maintenance notes

Row Level Security (RLS) is optional. When enabled, PostgreSQL enforces session isolation at the database level, preventing cross-session access even if application logic misses a filter.

If you prefer to manage the schema yourself, you can disable automatic initialization and run your own SQL scripts to set up tables and policies.

Available tools

read

Read file contents.

write

Write a file to a path, creating any missing parent directories automatically.

append

Append data to an existing file, creating the file if it does not exist.

stat

Check for existence and retrieve metadata about a path.

ls

List directory contents with directories first, then alphabetically.

mkdir

Create a directory, including any missing parent directories (mkdir -p behavior).

rm

Remove files or directories recursively.

mv

Move or rename a file or directory.

glob

Find files matching a glob pattern.

grep

Search file contents using a regular expression.

stores

List all named persistent stores available for cross-session storage.