mcp-virtual-fs

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

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