@undisk-mcp/local-proxy

[!IMPORTANT] AI makes mistakes! Undisk MCP makes recovery instant. Home: https://mcp.undisk.app Issues: https://github.com/kiarashplusplus/undisk-mcp-tracker/issues

An airlock between local LLMs and your filesystem.

When you run models locally with Ollama, LM Studio, or similar tools, giving them raw filesystem access is dangerous — a hallucinating agent can overwrite or delete critical files. This proxy enforces the same policy engine (path ACLs, size limits, extension rules) as Undisk's cloud service, but runs entirely on your machine. Every write creates a version backup so any mistake can be undone.

┌──────────────┐       stdio (JSON-RPC)       ┌─────────────────────┐
│  Claude /     │ ───────────────────────────▶ │  undisk-local-proxy │
│  Cursor /     │                              │                     │
│  Ollama       │ ◀─────────────────────────── │  ┌───────────────┐  │
└──────────────┘                               │  │ Policy Guard  │  │
                                               │  │ ─ Path ACLs   │  │
                                               │  │ ─ Size limits  │  │
                                               │  │ ─ Extensions   │  │
                                               │  └───────┬───────┘  │
                                               │          │          │
                                               │  ┌───────▼───────┐  │
                                               │  │ Local Storage  │  │
                                               │  │ + Versioning   │  │
                                               │  └───────────────┘  │
                                               └─────────────────────┘
                                                         │
                                                         ▼
                                               ┌─────────────────────┐
                                               │   Your Filesystem   │
                                               │  ./undisk-workspace  │
                                               │  .undisk-versions/   │
                                               └─────────────────────┘

Features

• Policy enforcement — path ACLs, size limits, and extension rules block dangerous operations before they reach your filesystem
• Version history — every write creates a backup; undo any change
• MCP over stdio — compatible with Claude Desktop, Cursor, Windsurf, and any MCP-aware tool
• Fully offline — no network calls, no telemetry, no phone-home
• Same API as cloud Undisk — read_file, write_file, list_files, search_files, move_file, list_versions, restore_version

Quick Start

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "undisk-local": {
      "command": "npx",
      "args": ["-y", "@undisk-mcp/local-proxy", "--root", "./workspace"]
    }
  }
}

Cursor / Windsurf

Add to your MCP settings:

{
  "mcpServers": {
    "undisk-local": {
      "command": "npx",
      "args": ["-y", "@undisk-mcp/local-proxy", "--root", "/path/to/workspace"]
    }
  }
}

Ollama (via MCP bridge)

If you're using an MCP bridge for Ollama, point it at the proxy:

npx @undisk-mcp/local-proxy --root ./workspace --policy policy.json

CLI Options

| Flag | Description | Default | |------|-------------|---------| | --root <path> | Workspace root directory | ./undisk-workspace | | --policy <path> | Path to policy JSON file | Built-in default | | -h, --help | Show help message | — |

The first positional argument (without --) is also accepted as the workspace root directory.

Policy File

Create a policy.json to control what the AI agent can do:

{
  "pathAcls": [
    { "pattern": "/secrets/**", "permission": "none" },
    { "pattern": "/config/**", "permission": "read" },
    { "pattern": "/**", "permission": "read-write" }
  ],
  "sizeLimits": [
    { "maxBytes": 10485760 }
  ],
  "extensionRules": [
    { "denied": [".exe", ".sh", ".bat"] }
  ]
}

Path ACL Permissions

| Permission | Read | Write | Delete | |------------|------|-------|--------| | read-write | ✅ | ✅ | ✅ | | read | ✅ | ❌ | ❌ | | append | ✅ | append-only | ❌ | | none | ❌ | ❌ | ❌ |

Patterns support * (single segment) and ** (any depth) glob syntax.

Default Policy

When no --policy flag is provided, the proxy uses a sensible default:

• Block access to dotfiles (/.*)
• Allow read-write to everything else (/**)
• 10 MB file size limit

Version History

Every write operation creates a version backup in .undisk-versions/ inside your workspace root. You can:

• List versions: Use the list_versions tool with a file path
• Restore: Use the restore_version tool with a file path and version ID
• Automatic backup: Even delete_file saves a version before removing

Version files are stored as:

.undisk-versions/
└── path/to/file/
    ├── v_1234567890_abc123.content    # File content
    └── v_1234567890_abc123.meta.json  # Version metadata

Available Tools

| Tool | Description | |------|-------------| | read_file | Read a file from the workspace | | write_file | Write content to a file (creates version backup) | | create_file | Create a new file | | delete_file | Delete a file (version preserved) | | list_files | List files in a directory | | search_files | Search file contents by pattern | | move_file | Move or rename a file | | list_versions | List version history for a file | | restore_version | Restore a file to a previous version |

License

MIT