Virtual Filesystem
About
PostgreSQL-backed virtual filesystem exposed via MCP tools. Persistent, session-isolated file operations for AI agents.
Details
- Author
- lu-zhengda
- GitHub stars
- 2
- Downloads
- 501
- Categories
- Other
Jump to
- Persistent file storage in PostgreSQL, surviving process restarts and container recycling
- Automatic session isolation with per-connection namespaces
- Cross-session named stores for sharing data between agents
- 11 POSIX-style tools: read, write, append, stat, ls, mkdir, rm, mv, glob, grep, stores
- Glob and grep search using PostgreSQL trigram indexes
- Optional Row Level Security for multi-tenant database-enforced isolation
- Zero configuration with auto-created tables on first run
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Virtual FilesystemCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Set up a PostgreSQL database (version 14 or later) and configure your MCP client to run npx -y mcp-virtual-fs with the DATABASE_URL environment variable and VFS_AUTO_INIT=true for automatic table creation. Then interact with the 11 POSIX-style tools (e.g., write, read, ls, glob, grep) which return structured JSON responses.
read
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.
write
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.
append
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.
stat
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.
ls
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.
mkdir
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.
rm
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.
mv
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.
glob
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.
grep
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.
stores
List all named persistent stores. Stores are cross-session namespaces for long-term data that persists indefinitely. Returns an array of store names.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"virtual filesystem": {
"virtual-fs": {
"command": "npx",
"args": [
"-y",
"mcp-virtual-fs"
],
"env": {
"DATABASE_URL": "<YOUR_POSTGRESQL_CONNECTION_STRING>",
"VFS_AUTO_INIT": "true"
}
}
}
}
}McpServers
{
"virtual-fs": {
"command": "npx",
"args": [
"-y",
"mcp-virtual-fs"
],
"env": {
"DATABASE_URL": "<YOUR_POSTGRESQL_CONNECTION_STRING>",
"VFS_AUTO_INIT": "true"
}
}
}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
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
