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

... View full README on GitHub