Skip to main content
Glama
mcp-virtual-fs

mcp-virtual-fs

by lu-zhengda

mcp-virtual-fs

npm version CI npm downloads License: MIT Node.js

An MCP server that provides AI agents with a persistent, PostgreSQL-backed virtual filesystem. Supports session-isolated file operations, cross-session shared stores, glob/grep search, and Row Level Security — all exposed as standard Model Context Protocol tools.

Works with any MCP client: Claude Desktop, Claude Code, Cursor, Windsurf, Cline, and others.

Features

  • Persistent file storage — files are stored in PostgreSQL and survive process restarts, container recycling, and redeployments

  • Session isolation — each agent session gets its own namespace automatically, no configuration needed

  • Cross-session stores — named persistent stores for sharing data between agents or for long-term agent memory

  • 11 POSIX-style tools — read, write, append, stat, ls, mkdir, rm, mv, glob, grep, stores

  • Glob and grep search — find files by pattern (**/*.ts) or search content by regex, powered by PostgreSQL trigram indexes

  • Row Level Security — optional database-enforced isolation between sessions for multi-tenant deployments

  • Zero config — auto-creates tables on first run with VFS_AUTO_INIT=true

Related MCP server: persistent-memory

Use Cases

  • Agent scratchpad — give LLM agents a persistent workspace to read/write files across tool calls

  • Long-term agent memory — store notes, context, and knowledge across sessions using named stores

  • Multi-agent collaboration — multiple agents share files through cross-session stores

  • Sandboxed file operations — agents interact with a virtual filesystem instead of the host OS

  • CI/CD artifact storage — persist build outputs, logs, and reports in a queryable filesystem

Why

Agents work well with filesystems for context management, but coupling storage to the agent runtime means data is lost when pods restart or containers are recycled. This MCP server decouples storage from runtime by moving file operations to PostgreSQL — giving agents persistent, isolated, and searchable file storage without touching the host filesystem.

Prerequisites

  • Node.js 20 or later

  • PostgreSQL 14 or later (with pg_trgm extension — included in most distributions)

Quick Start

1. Set up PostgreSQL

# Using Docker
docker run -d --name vfs-postgres \
  -e POSTGRES_DB=vfs \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:16-alpine

2. Configure your MCP client

Add to your MCP client config (e.g., Claude Desktop claude_desktop_config.json or Claude Code .mcp.json):

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

That's it. VFS_AUTO_INIT=true creates the tables on first run.

3. Use the tools

Tool names are short POSIX-style names:

write({ path: "/notes/todo.md", content: "# My Tasks\n- Ship feature" })
read({ path: "/notes/todo.md" })
ls({ path: "/notes" })
glob({ pattern: "**/*.md" })
grep({ pattern: "TODO" })

All tools return structured JSON responses.

Tools

Tool

Parameters

Returns

Description

read

path

{content, size}

Read file contents

write

path, content

{path, size, has_parents}

Write file (creates parents automatically)

append

path, content

{path, appended_bytes}

Append to file (creates if missing)

stat

path

{exists, type?, size?, children?}

Check existence and get metadata

ls

path

{entries: [{name, type}]}

List directory (dirs first, then alphabetical)

mkdir

path

{path, already_existed}

Create directory and parents (mkdir -p)

rm

path

{path, deleted}

Remove file or directory recursively

mv

source, destination

{source, destination}

Move/rename file or directory

glob

pattern

{files, count}

Find files by glob (e.g., **/*.ts, **/*.{js,ts})

grep

pattern, path_filter?

{matches, count}

Search file contents by regex

stores

(none)

{stores, count}

List all persistent store names

All tools (except stores) accept an optional store parameter for cross-session persistent storage.

Session Management

Sessions are handled automatically — no session ID in tool parameters.

How it works:

Transport

Session identity

Behavior

stdio

Auto-generated UUID per process

Each MCP connection = unique session

HTTP/SSE

Transport-provided sessionId

MCP protocol handles it

Any

VFS_SESSION_ID env var

Deterministic/resumable sessions

Priority: transport sessionId > VFS_SESSION_ID env var > auto-generated UUID.

Resumable sessions

To resume a previous session across process restarts, set a deterministic session ID:

{
  "env": {
    "DATABASE_URL": "postgresql://...",
    "VFS_SESSION_ID": "my-agent-session-1"
  }
}

Cross-Session Stores

Named stores persist across sessions. Any session can read/write to a store by passing the store parameter:

// Session A writes to a store
write({ path: "/context.md", content: "project notes", store: "agent-memory" })

// Session B (days later) reads from the same store
read({ path: "/context.md", store: "agent-memory" })

// Without `store`, operations target the session's own namespace
write({ path: "/scratch.txt", content: "session-only data" })

// List all available stores
stores()

Stores are auto-created on first use.

Environment Variables

Variable

Required

Default

Description

DATABASE_URL

Yes

—

PostgreSQL connection string

VFS_AUTO_INIT

No

false

Auto-create tables on startup

VFS_SESSION_ID

No

random UUID

Deterministic session ID

VFS_ENABLE_RLS

No

false

Enable Row Level Security

VFS_STORAGE_BACKEND

No

postgres

Storage backend type

Manual Database Setup

If you prefer to manage the schema yourself instead of using VFS_AUTO_INIT:

psql $DATABASE_URL -f sql/schema.sql

Row Level Security (optional)

RLS provides database-enforced session isolation. Even if application code has a bug that omits a WHERE session_id = clause, PostgreSQL itself prevents cross-session access.

# Run after schema.sql
psql $DATABASE_URL -f sql/rls.sql

# Update the vfs_app password
psql $DATABASE_URL -c "ALTER ROLE vfs_app PASSWORD 'your-secure-password'"

Then configure the MCP server to connect as vfs_app:

{
  "env": {
    "DATABASE_URL": "postgresql://vfs_app:your-secure-password@localhost:5432/vfs",
    "VFS_ENABLE_RLS": "true"
  }
}

Development

Requirements

  • Node.js 20+

  • Docker (for integration tests — runs PostgreSQL via testcontainers)

git clone https://github.com/lu-zhengda/mcp-virtual-fs.git
cd mcp-virtual-fs
npm install
npm run build

Commands

Command

Description

npm run build

Compile TypeScript

npm test

Run all tests (requires Docker)

npm run test:unit

Run unit tests only

npm run test:integration

Run integration tests only

npm run lint

Run ESLint

npm run lint:fix

Auto-fix lint issues

npm run dev

Run with tsx (no build step)

Testing

Tests use testcontainers to spin up real PostgreSQL instances in Docker. No mocks — the integration tests exercise actual SQL queries, trigram indexes, and RLS policies.

# Requires Docker running
npm test

Session Cleanup

Ephemeral sessions can be cleaned up periodically:

DELETE FROM vfs_sessions
WHERE is_persistent = false
  AND created_at < now() - interval '7 days';

The ON DELETE CASCADE on vfs_nodes handles file cleanup automatically. Persistent stores (created via the store parameter) are never affected.

License

MIT

Available Tools

11 tools
appendA

Append content to the end of a file. Creates the file if it doesn't exist. Parent directories are created automatically. Useful for logs or incrementally building files. The 10 MB limit is per call — total file size is not capped. Errors: EISDIR if the path is an existing directory, EINVAL if appending to root.

Inputs: path (required), content (required), store.

globA
Read-only

Find files matching a glob pattern. Supports wildcards (.ts), recursive matching (**/.md), and brace expansion ({py,json}). Returns an array of matching file paths. Only matches files, not directories.

Inputs: pattern (required), store.

grepA
Read-only

Search file contents using a regular expression. Returns matching lines with file path and line number. Optimized for fast content search across all files. Optionally filter which files to search with a path glob.

Inputs: pattern (required), path_filter, store.

lsA
Read-only

List the contents of a directory. Returns an array of entries, each with a name and type (file or directory). Entries are sorted with directories first, then alphabetically. Errors: ENOENT if the directory does not exist, ENOTDIR if the path is a file.

Inputs: path (required), store.

mkdirA
Idempotent

Create a directory and any missing parent directories (mkdir -p behavior). Idempotent — succeeds even if the directory already exists. Returns whether the directory already existed. Errors: EEXIST if a file (not directory) already exists at the path.

Inputs: path (required), store.

mvA

Move or rename a file or directory. Moves all descendants when moving a directory. Parent directories at the destination are created automatically. Errors: ENOENT if source doesn't exist, EEXIST if destination already exists, EINVAL if moving root or moving a directory into itself.

Inputs: source (required), destination (required), store.

readA
Read-only

Read the contents of a file. Returns the file content and size in bytes. Errors: ENOENT if the file does not exist, EISDIR if the path is a directory.

Inputs: path (required), store.

rmA
Destructive

Remove a file or directory. Directories are removed recursively including all descendants. This operation is non-recoverable — there is no undo or trash. Returns the total number of nodes deleted. Errors: ENOENT if the path does not exist, EINVAL if attempting to remove root.

Inputs: path (required), store.

statA
Read-only

Check whether a path exists and get metadata about it. Returns exists (boolean), and if it exists: type (file or directory), size (bytes, for files), or children count (for directories). Never errors — returns {exists: false} for missing paths.

Inputs: path (required), store.

storesA
Read-only

List all named persistent stores. Stores are cross-session namespaces for long-term data that persists indefinitely. Returns an array of store names.

Inputs: no named parameters.

writeA
Idempotent

Write content to a file, creating it if it doesn't exist. Parent directories are created automatically (mkdir -p). Overwrites existing file content entirely. Errors: EISDIR if the path is an existing directory, EINVAL if writing to root.

Inputs: path (required), content (required), store.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool has a distinct file system operation (read, write, list, delete, search, etc.) with no functional overlap. An agent can easily distinguish between them.

    Naming Consistency5/5

    Tool names are all lowercased single words, mostly verbs (append, glob, grep, ls, mkdir, mv, read, rm, stat, write) with one noun (stores). This follows a consistent command-like pattern.

    Tool Count5/5

    With 11 tools, the server provides a comprehensive but not overwhelming set of file system operations. The count is well-scoped for the domain.

    Completeness4/5

    The tool set covers most file system operations including create, read, update, delete, search, and metadata. However, a copy operation is missing, which is a notable gap for a file system server.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers