Vulcan File Ops

Secure • User-Controlled • High-Performance File Operations Server

Transform your desktop AI assistants into powerful development partners. Vulcan File Ops bridges the gap between conversational AI (Claude Desktop, ChatGPT Desktop, etc.) and your local filesystem, unlocking the same file manipulation capabilities found in AI-powered IDEs like Cursor and VS Code extension like Cline. Write code, refactor projects, manage documentation, and perform complex file operations—matching the power of dedicated AI coding assistants. With enterprise-grade security controls, dynamic directory registration, and intelligent tool filtering, you maintain complete control while your AI assistant handles the heavy lifting.

- Background
- Install
- Usage
- API

- Read Operations

- read_file
- attach_image
- read_multiple_files

- write_file
- write_multiple_files
- edit_file

- make_directory
- list_directory
- move_file
- file_operations
- delete_files
- get_file_info
- register_directory
- list_allowed_directories

TheModel Context Protocol(MCP) enables AI assistants to securely access external resources and services. This server implements MCP for filesystem operations, allowing AI agents to read, write, and manage files within controlled directory boundaries.

For developerswho want to contribute or modify the code, seeLocal Repository Executionbelow.

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

- Download Node.js:https://nodejs.org/
- Check installation: Runnode --versionandnpm --version

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

[mcp_servers.vulcan_file_ops] command = "npx" args = ["-y", "@n0zer0d4y/vulcan-file-ops"] enabled = true startup_timeout_sec = 120.0

After runningnpm install -g @n0zer0d4y/vulcan-file-ops:

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

After runningnpm install @n0zer0d4y/vulcan-file-opsin your project:

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

Option 4: Local Repository Execution (For Developers)

If you've cloned this repository and want to run from source:

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

{ "mcpServers": { "vulcan-file-ops": { "command": "node", "args": [ "/absolute/path/to/vulcan-file-ops/dist/cli.js", "--approved-folders", "/path/to/your/allowed/directories" ] } } }

[mcp_servers.vulcan_file_ops] command = "node" args = [ 'C:\absolute\path\to\vulcan-file-ops\dist\cli.js', "--approved-folders", 'C:\path\to\your\allowed\directories' ] cwd = 'C:\absolute\path\to\vulcan-file-ops' enabled = true startup_timeout_sec = 120.0

Note:For local repository execution, prefernode dist/cli.jswith an absolute path. This works reliably in Codex and avoids PATH ambiguity.

Pre-configure specific directories for immediate access on server start:

{ "mcpServers": { "vulcan-file-ops": { "command": "npx", "args": [ "-y", "@n0zer0d4y/vulcan-file-ops", "--approved-folders", "/Users/username/projects", "/Users/username/documents" ] } } }

{ "mcpServers": { "vulcan-file-ops": { "command": "npx", "args": [ "-y", "@n0zer0d4y/vulcan-file-ops", "--approved-folders", "C:/Users/username/projects", "C:/Users/username/documents" ] } } }

For users running from a cloned repository (afternpm run build):

{ "mcpServers": { "vulcan-file-ops": { "command": "vulcan-file-ops", "args": [ "--approved-folders", "/Users/username/projects", "/Users/username/documents" ] } } }

Codex with Approved Folders (config.toml)

[mcp_servers.vulcan_file_ops] command = "node" args = [ 'C:\absolute\path\to\vulcan-file-ops\dist\cli.js', "--approved-folders", 'C:\Users\username\projects', 'C:\Users\username\documents' ] cwd = 'C:\absolute\path\to\vulcan-file-ops' enabled = true startup_timeout_sec = 120.0

- Windows: Include drive letter (e.g.,C:/,D:/). Use forward slashes in JSON to avoid escaping backslashes.
- macOS/Linux: Start with/for absolute paths, or use~for home directory.

- Instant Access: Directories are validated and ready immediately when server starts
- Security: Only specified directories are accessible (unless using MCP Roots protocol)
- Convenience: No need to manually register directories via conversation
- AI Visibility: Approved directories are dynamically embedded inregister_directoryandlist_allowed_directoriestool descriptions, ensuring AI assistants can see which directories are pre-approved and avoid redundant registration attempts

When you configure--approved-folders, the server dynamically injects this information into the tool descriptions forregister_directoryandlist_allowed_directories. This ensures:

- ✅ AI assistants can see which directories are already accessible
- ✅ AI knows NOT to re-register pre-approved directories or their subdirectories
- ✅ Clear visibility without requiring the AI to calllist_allowed_directoriesfirst
- ✅ Works reliably across all MCP clients (including Cursor, Claude Desktop, etc.)

Example of what AI sees in tool description:

PRE-APPROVED DIRECTORIES (already accessible, DO NOT register these): - C:\Users\username\projects - C:\Users\username\documents IMPORTANT: These directories and their subdirectories are ALREADY accessible to all filesystem tools. Do NOT use register_directory for these paths.

- Paths must be absolute: Windows requires drive letter (C:/path), Unix/Mac starts with/or~
- Comma-separated list of directories (no spaces unless part of path)
- Directories are validated on startup; server will exit if any path is invalid
- Works alongside runtimeregister_directorytool for additional access
- MCP Roots protocol (if used by client) will replace approved folders with workspace roots

Exclude specific folders from directory listings:

{ "mcpServers": { "vulcan-file-ops": { "command": "npx", "args": [ "@n0zer0d4y/vulcan-file-ops", "--ignored-folders", "node_modules,dist,.git,.next" ] } } }

{ "mcpServers": { "vulcan-file-ops": { "command": "npx", "args": [ "@n0zer0d4y/vulcan-file-ops", "--enabled-tool-categories", "read,filesystem" ] } } }

{ "mcpServers": { "vulcan-file-ops": { "command": "npx", "args": [ "@n0zer0d4y/vulcan-file-ops", "--enabled-tools", "read_file,list_directory,grep_files" ] } } }

All configuration options can be combined:

{ "mcpServers": { "vulcan-file-ops": { "command": "npx", "args": [ "@n0zer0d4y/vulcan-file-ops", "--approved-folders", "C:/Users/username/projects", "C:/Users/username/documents", "--ignored-folders", "node_modules,dist,.git", "--approved-commands", "npm,node,git,ls,pwd,cat,echo", "--enabled-tool-categories", "read,filesystem,shell", "--enabled-tools", "read_file,attach_image,read_multiple_files,write_file,write_multiple_files,edit_file,make_directory,list_directory,move_file,file_operations,delete_files,get_file_info,register_directory,list_allowed_directories,glob_files,grep_files,execute_shell" ] } } }

{ "mcpServers": { "vulcan-file-ops": { "command": "npx", "args": [ "@n0zer0d4y/vulcan-file-ops", "--approved-folders", "/Users/username/projects", "/Users/username/documents", "--ignored-folders", "node_modules,dist,.git", "--approved-commands", "npm,node,git,ls,pwd,cat,echo", "--enabled-tool-categories", "read,filesystem,shell", "--enabled-tools", "read_file,attach_image,read_multiple_files,write_file,write_multiple_files,edit_file,make_directory,list_directory,move_file,file_operations,delete_files,get_file_info,register_directory,list_allowed_directories,glob_files,grep_files,execute_shell" ] } } }

For users running from a cloned repository (afternpm run build):

{ "mcpServers": { "vulcan-file-ops": { "command": "vulcan-file-ops", "args": [ "--approved-folders", "/Users/username/projects", "/Users/username/documents", "--ignored-folders", "node_modules,dist,.git", "--approved-commands", "npm,node,git,ls,pwd,cat,echo", "--enabled-tool-categories", "read,filesystem,shell", "--enabled-tools", "read_file,attach_image,read_multiple_files,write_file,write_multiple_files,edit_file,make_directory,list_directory,move_file,file_operations,delete_files,get_file_info,register_directory,list_allowed_directories,glob_files,grep_files,execute_shell" ] } } }

To access a specific directory, instruct the AI agent:

"Please register the directory C:\path\to\your\folder for access, then list its contents."

The AI will use theregister_directorytool to gain access, then perform operations within that directory.

Read file contents with flexible modes (full, head, tail, range)

Note:This tool is limited to single-file operations only.RECOMMENDED:Useread_multiple_filesinstead, which supports both single and batch file operations for greater flexibility.

- path(string): File path
- mode(string, optional): Read mode

- full- Read entire file (default)
- head- Read first N lines
- tail- Read last N lines
- range- Read arbitrary line range (e.g., lines 50-100)

Output:File contents as text. Supports text files and documents (PDF, DOCX, PPTX, XLSX, ODT, ODP, ODS)

- path(string | string[]): Path to image file, or array of paths to attach multiple images at once

Output:Image content in MCP format for vision model processing. Supports PNG, JPEG, GIF, WebP, BMP, SVG

- files(array): List of file objects with path and optional mode settings

Output:Contents of all files. Failed reads don't stop the operation

Note:This tool is limited to single-file operations only.RECOMMENDED:Usewrite_multiple_filesinstead, which supports both single and batch file operations for greater flexibility.

- If the target file's parent directory does not exist but is inside your configured approved folders, the server will automatically create the required directory structure before writing the file
- If the path is outside approved folders, the operation fails with a clear error and no directories are created

- path(string): File path
- content(string): File content (text or HTML for PDF/DOCX conversion)

Output:Success confirmation. Supports HTML-to-PDF/DOCX conversion with rich formatting

Create or replace multiple files concurrently

- For each requested file, if the parent directory does not exist but is inside your configured approved folders, the server will automatically create the required directory structure before writing
- Paths outside approved folders are rejected during validation and no directories are created; the operation fails with a detailed list of invalid paths

- files(array): List of file objects with path and content

Output:Status for each file. Failed writes don't stop other files

Apply precise modifications to text and code files with intelligent matching. Supports both single-file and multi-file operations.

Single File Input (mode: 'single'):

- mode(string, optional): Set to"single"(default if omitted for backward compatibility)
- path(string): File path
- edits(array): List of edit operations, each containing:

- oldText(string): Text to search for (include 3-5 lines of context)
- newText(string): Text to replace with
- instruction(string, optional): Description of what this edit does
- expectedOccurrences(number, optional): Expected match count (default: 1)

- exact- Character-for-character match (fastest, safest)
- flexible- Whitespace-insensitive matching, preserves indentation
- fuzzy- Token-based regex matching (most permissive)
- auto- Try exact → flexible → fuzzy (default)

Multi-File Input (mode: 'multiple'):