vulcan-file-ops

Vulcan File Ops MCP Server exposes a secure, local-first filesystem operation layer driven by MCP. It lets AI assistants read, write, edit, and manage files within controlled directories you approve or register at runtime. Core capabilities include reading and writing documents (PDF, DOCX, PPTX, XLSX, ODT), attaching images for vision tasks, and performing batch operations across multiple files. The server also provides directory filtering, dynamic directory registration, and strict path validation to keep your local data safe. You can enable or constrain specific tools or tool categories to tailor the AI's file operations to your workflows.

To use the server in your MCP client, configure the client to launch Vulcan File Ops via npx (recommended) or a local/global installation. The README describes several configuration options, such as starting with pre-approved folders or running from a local repository during development. Once started, you can instruct the AI to call the available API endpoints (read_file, write_file, make_directory, list_directory, move_file, delete_files, etc.) through the MCP protocol, and the server will enforce the registered directory boundaries and security controls.

Prerequisites

• Node.js (version 14 or higher) with npm installed
• Access to a terminal/command prompt

Installation options

1. Quick start (npx, no install):

npx @n0zer0d4y/vulcan-file-ops --help

2. Global installation (system-wide):

npm install -g @n0zer0d4y/vulcan-file-ops

3. Local installation (per-project):

npm install @n0zer0d4y/vulcan-file-ops

4. Local repository execution (developing from source):

git clone https://github.com/n0zer0d4y/vulcan-file-ops.git
cd vulcan-file-ops
npm install
npm run build

Configure your MCP client to point at the local or npx-executed binary. Examples from the README show several options:

Using npx (recommended):

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": ["@n0zer0d4y/vulcan-file-ops"]
    }
  }
}

Using a globally installed binary:

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "vulcan-file-ops"
    }
  }
}

Using a locally installed binary:

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "./node_modules/.bin/vulcan-file-ops"
    }
  }
}

Advanced/local-repo start example (with approved folders):

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "vulcan-file-ops",
      "args": ["--approved-folders", "/path/to/your/allowed/directories"]
    }
  }
}

Notes: The README mentions that the vulcan-file-ops command will be available in PATH after building, or you can use the full path to the built CLI (e.g., ./dist/cli.js).

Tips and common considerations:

• Use approved folders to quickly grant trusted access on startup, and supplement with runtime registration via the register_directory tool for flexibility.
• Ensure sensitive directories (like system or project metadata folders) are excluded by default using directory filtering to keep MCP responses concise and secure.
• When using npx, you always pull the latest version unless you pin a version in your MCP config. If you need reproducible builds, prefer a local/global install and specify the exact binary path.
• If you enable advanced editing features, consider diff previews and explicit user approval for destructive operations (delete, move, or edit with pattern-based changes).
• Monitor and configure environment variables as needed for your environment (e.g., logging levels, allowed directories, or shell command approvals) via your MCP client or through a dedicated config file if supported by the server.