# Mcp Virtual Fs

> PostgreSQL-backed virtual filesystem exposed via MCP tools. Persistent, session-isolated file operations for AI agents.

- **Type:** MCP server
- **Install:** `agentstack add mcp-lu-zhengda-mcp-virtual-fs`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [lu-zhengda](https://agentstack.voostack.com/s/lu-zhengda)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [lu-zhengda](https://github.com/lu-zhengda)
- **Source:** https://github.com/lu-zhengda/mcp-virtual-fs
- **Website:** https://www.npmjs.com/package/mcp-virtual-fs

## Install

```sh
agentstack add mcp-lu-zhengda-mcp-virtual-fs
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mcp-virtual-fs

[](https://www.npmjs.com/package/mcp-virtual-fs)
[](https://github.com/lu-zhengda/mcp-virtual-fs/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/mcp-virtual-fs)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)

An [MCP server](https://modelcontextprotocol.io/) 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](https://modelcontextprotocol.io/) 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
# 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`):

```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:

```json
{
  "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`:

```bash
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.

```bash
# 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`:

```json
{
  "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](https://node.testcontainers.org/))

```bash
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](https://node.testcontainers.org/) to spin up real PostgreSQL instances in Docker. No mocks — the integration tests exercise actual SQL queries, trigram indexes, and RLS policies.

```bash
# Requires Docker running
npm test
```

## Session Cleanup

Ephemeral sessions can be cleaned up periodically:

```sql
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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [lu-zhengda](https://github.com/lu-zhengda)
- **Source:** [lu-zhengda/mcp-virtual-fs](https://github.com/lu-zhengda/mcp-virtual-fs)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/mcp-virtual-fs

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-lu-zhengda-mcp-virtual-fs
- Seller: https://agentstack.voostack.com/s/lu-zhengda
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.