# virtual-fs [Health: Active]

**Category:** 📂 File Systems  
**Repository:** https://github.com/lu-zhengda/mcp-virtual-fs  
**GitHub Stars:** 3  
**npm Downloads (last month):** 159  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/virtual-fs

## Description
PostgreSQL-backed virtual filesystem for AI agents with persistent, session-isolated storage.

## Tools
Capabilities this server exposes over MCP:

- **read** — Read file contents
- **write** — Write file (creates parents automatically)
- **append** — Append to file (creates if missing)
- **stat** — Check existence and get metadata
- **ls** — List directory (dirs first, then alphabetical)
- **mkdir** — Create directory and parents (mkdir -p)
- **rm** — Remove file or directory recursively
- **mv** — Move/rename file or directory
- **glob** — Find files by glob (e.g., `**/*.ts`, `**/*.{js,ts}`)
- **grep** — Search file contents by regex
- **stores** — List all persistent store names

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "virtual-fs": {
    "command": "npx",
    "args": ["-y","mcp-virtual-fs"],
    "env": {
      "DATABASE_URL": ""
    }
  }
}
```

**Requires environment variables:** `DATABASE_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What virtual-fs does

The virtual-fs MCP server presents a file-oriented interface backed by PostgreSQL. Agent operations are stored in the database rather than on the machine running the MCP process, so files remain available after process restarts, container recycling, and redeployments. The server is suitable for agent scratch work, persistent notes, build outputs, logs, reports, and other data that benefits from a filesystem-shaped API.

Each connection gets a session namespace by default. This keeps one agent session's files separate from another session's files without requiring a session argument in every tool call. Named stores provide an alternative namespace for information that should be shared between sessions or kept as longer-term memory.

## How it works

The virtual-fs MCP server uses PostgreSQL as its storage backend and requires PostgreSQL 14 or newer with the `pg_trgm` extension. Node.js 20 or later is also required. The server can initialize its tables on startup when `VFS_AUTO_INIT=true`; otherwise, the schema can be applied manually with the supplied SQL file.

Session identity depends on the transport and configuration. Stdio connections receive a generated UUID for each process, while HTTP/SSE connections use the transport-provided MCP session ID. Setting `VFS_SESSION_ID` provides a deterministic or resumable identity, but transport session identity has priority. Passing a `store` parameter switches an operation from the current session namespace to a named persistent store. Stores are created when first used, and the `stores` tool lists their names.

Optional PostgreSQL Row Level Security can add database-enforced isolation for multi-tenant deployments. RLS requires applying the provided RLS SQL and configuring the server with an appropriate database role.

## Setup and configuration

Provide `DATABASE_URL` in the MCP client's environment. A typical configuration runs the package with `npx`, points it at PostgreSQL, and sets `VFS_AUTO_INIT=true` for first-run table creation. Manual schema management is also supported with `psql $DATABASE_URL -f sql/schema.sql`.

Available environment variables include:

- `DATABASE_URL`: PostgreSQL connection string; required.
- `VFS_AUTO_INIT`: creates tables at startup when enabled; defaults to `false`.
- `VFS_SESSION_ID`: optional deterministic session identifier.
- `VFS_ENABLE_RLS`: enables Row Level Security when set up in the database; defaults to `false`.
- `VFS_STORAGE_BACKEND`: selects the storage backend and defaults to `postgres`.

## Tools and capabilities

The virtual-fs MCP server exposes these tools:

- `read` returns file content and size.
- `write` creates or replaces a file and creates missing parent directories.
- `append` adds content to a file or creates it when absent.
- `stat` reports whether a path exists and returns available metadata.
- `ls` lists directory entries, placing directories first and sorting alphabetically.
- `mkdir` creates a directory and any missing parents.
- `rm` removes a file or recursively removes a directory.
- `mv` moves or renames a file or directory.
- `glob` finds paths using patterns such as `**/*.ts` or brace extensions.
- `grep` searches file contents with a regular expression and can accept a path filter.
- `stores` lists persistent store names.

All tools except `stores` accept the optional `store` parameter. Responses use structured JSON, which lets an agent inspect results such as file sizes, match counts, directory entries, and deletion status.

_Full upstream README: https://allmcps.com/mcp/virtual-fs/readme_