Vulcan File Ops

Vulcan File Ops MCP Server lets AI assistants securely interact with your local filesystem through multiple configurable access modes. Run entirely locally, enforce strict directory boundaries, and perform high‑volume file operations, edits, and shell commands under controlled permissions. This guide walks you through practical usage, installation steps, and important configuration details so you can integrate Vulcan File Ops with your MCP client and start working with files safely and efficiently.

How to use

You connect Vulcan File Ops to an MCP client to perform read, write, and filesystem operations within approved directories. Start by choosing how you want to run the server: use npx for instant execution, install globally, install locally in a project, or run from a local repository for development. Once running, you register directories you want to access and then issue commands through your MCP client to read files, create or modify documents, manage folders, execute shell commands (with safety checks), and attach images for vision analysis.

How to install

Prerequisites: Node.js version 14 or higher must be installed on your system. This provides npm and npx, which are required to run the server.

Choose one of the following installation methods.

Quick Start (Recommended) Run directly without installation to get the latest version via npx.

Install globally for system-wide access.

Install locally in a project.

Additional setup and examples

Configure your MCP client with the appropriate server entry. You can run Vulcan File Ops via npx, or install it locally/global and reference the binary accordingly.

If you want to run from a cloned repository for development, clone, install dependencies, build, and start the server. Then point your MCP client to the resulting executable.

Security and usage notes

All operations are validated against registered/approved directories. You can register directories at runtime via the register_directory tool or specify approved folders at startup. The server enforces strict path validation, supports directory filtering, and requires shell command approval for any execution that touches the filesystem.

Example usage flow

1. Start Vulcan File Ops via your preferred method (npx, global, local, or repo start). 2) Pre-approve folders you want AI access to, or register new directories at runtime. 3) In your MCP client, configure a vulcan-file-ops entry and begin issuing read/write/file-management commands. 4) When needed, attach images for AI vision analysis and receive descriptive results.

Available tools

read_file

Read file contents with flexible modes (full/head/tail/range) and support for documents (PDF/DODX/Office formats) in a single-file operation.

attach_image

Attach images for AI vision analysis with support for multiple images in one call.

read_multiple_files

Batch read multiple files concurrently with per-file mode options.

write_file

Create or replace a single file, with optional HTML-to-PDF/DOCX conversion and automatic directory creation within approved folders.

write_multiple_files

Create or replace multiple files concurrently with automatic directory creation for approved folders.

edit_file

Apply precise edits to text and code with multiple matching strategies and detailed diff output.

make_directory

Create one or more directories recursively, similar to mkdir -p.

list_directory

List contents of a directory in several formats and with optional exclusion patterns.

move_file

Relocate or rename a single file or directory.

file_operations

Bulk operations (move/copy/rename) on multiple files with conflict resolution.

delete_files

Delete one or more files or directories with optional recursive/force options.

get_file_info

Retrieve metadata for files and directories.

register_directory

Dynamically enable runtime access to new directories.

list_allowed_directories

Display currently accessible directory paths.

glob_files

Find files using glob pattern matching.

grep_files

Search for text patterns within files with optional context.

execute_shell

Execute shell commands with built-in security checks and path validation.