mcp-virtual-fs
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-virtual-fs save a new file named todo.md with my daily tasks"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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,storesGlob and grep search — find files by pattern (
**/*.ts) or search content by regex, powered by PostgreSQL trigram indexesRow 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_trgmextension — 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-alpine2. 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 file contents |
|
|
| Write file (creates parents automatically) |
|
|
| Append to file (creates if missing) |
|
|
| Check existence and get metadata |
|
|
| List directory (dirs first, then alphabetical) |
|
|
| Create directory and parents (mkdir -p) |
|
|
| Remove file or directory recursively |
|
|
| Move/rename file or directory |
|
|
| Find files by glob (e.g., |
|
|
| Search file contents by regex |
| (none) |
| 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 | MCP protocol handles it |
Any |
| 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 |
| Yes | — | PostgreSQL connection string |
| No |
| Auto-create tables on startup |
| No | random UUID | Deterministic session ID |
| No |
| Enable Row Level Security |
| No |
| 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.sqlRow 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 buildCommands
Command | Description |
| Compile TypeScript |
| Run all tests (requires Docker) |
| Run unit tests only |
| Run integration tests only |
| Run ESLint |
| Auto-fix lint issues |
| 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 testSession 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 toolsappendA
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.
globARead-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.
grepARead-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.
lsARead-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.
mkdirAIdempotent
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.
readARead-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.
rmADestructive
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.
statARead-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.
storesARead-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.
writeAIdempotent
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
Scored across 11 tools
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.
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.
With 11 tools, the server provides a comprehensive but not overwhelming set of file system operations. The count is well-scoped for the domain.
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
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Persistent file storage for AI agents. Save files over MCP, get a link a human can open.
Persistent file storage for AI agents via MCP and curl. Upload, download, and version files.
Cloud-hosted MCP server for durable AI memory
Related MCP Servers
- AlicenseAqualityCmaintenanceA universal MCP server that provides AI agents with structured tools for filesystem, database, shell, and git operations, enabling seamless interaction with projects.19MIT
- AlicenseNot gradedqualityCmaintenanceA self-hostable MCP server that provides permanent memory for AI agents using Postgres + pgvector for semantic search and Markdown file sync.MIT
- AlicenseNot gradedqualityCmaintenanceMCP server providing AI agents with persistent shells, filesystem access, and multi-machine management backed by Docker containers or remote SSH hosts.1AGPL 3.0
- AlicenseAqualityDmaintenanceMCP server providing persistent memory for AI agents, enabling them to read, write, and query memories across sessions.915 npmMIT