Vulcan File Ops

Vulcan File Ops MCP Server

[](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.n0zer0d4y/vulcan-file-ops)

[](https://modelcontextprotocol.io) [](https://modelcontextprotocol.io) [](https://github.com/RichardLitt/standard-readme) [](https://opensource.org/licenses/MIT) [](https://mseep.ai/app/n0zer0d4y-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.

Table of Contents

• [Background](#background)
• [Install](#install)
• [Usage](#usage)
• [API](#api)
• [Read Operations](#read-operations)
• [readfile](#readfile)
• [attachimage](#attachimage)
• [readmultiplefiles](#readmultiplefiles)
• [Write Operations](#write-operations)
• [writefile](#writefile)
• [writemultiplefiles](#writemultiplefiles)
• [editfile](#editfile)
• [Filesystem Operations](#filesystem-operations)
• [makedirectory](#makedirectory)
• [listdirectory](#listdirectory)
• [movefile](#movefile)
• [fileoperations](#fileoperations)
• [deletefiles](#deletefiles)
• [getfileinfo](#getfileinfo)
• [registerdirectory](#registerdirectory)
• [listalloweddirectories](#listalloweddirectories)
• [Search Operations](#search-operations)
• [globfiles](#globfiles)
• [grepfiles](#grepfiles)
• [Shell Operations](#shell-operations)
• [executeshell](#executeshell)
• [Security](#security)
• [Contributing](#contributing)
• [License](#license)

Background

Model Context Protocol

The Model 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.

Key Features

This enhanced implementation provides:

• Dynamic Directory Access: Runtime directory registration through conversational commands
• Document Support: Read/write PDF, DOCX, PPTX, XLSX, ODT with HTML-to-document conversion
• Batch Operations: Read, write, edit, copy, move, or rename multiple files concurrently
• Advanced File Editing: Pattern-based modifications with flexible matching and diff preview
• Flexible Reading Modes: Full file, head/tail, or arbitrary line ranges
• Image Vision Support: Attach images for AI analysis and description
• Directory Filtering: Exclude unwanted folders (nodemodules, dist, .git) from listings as listdirectory tool can bloat server output if these types folders, normally gitignored, are included
• Selective Tool Activation: Enable only specific tools or tool categories
• High Performance: Optimized search algorithms with smart recursion detection
• Security Controls: Path validation, access restrictions, and shell command approval
• Local Control: Full local installation with no external dependencies

Directory Access Model

This server supports multiple flexible approaches to directory access:

1. Pre-configured Access: Use --approved-folders to specify directories on server start for immediate access
2. Runtime Registration: Users can instruct AI agents to register directories during conversation via register_directory tool
3. MCP Roots Protocol: Client applications can provide workspace directories dynamically
4. Flexible Permissions: Combine multiple approaches - start with approved folders, add more at runtime
5. Secure Boundaries: All operations validate against registered directories regardless of access method

Install

This server requires Node.js and can be installed globally, locally, or run directly with npx. Most users should use npx for instant execution without installation.

Quick Start (Recommended for Most Users)

Run directly without installation:

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

For developers who want to contribute or modify the code, see [Local Repository Execution](#option-4-local-repository-execution-for-developers) below.

Global Installation

Install globally for system-wide access:

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

Local Installation

Install in a specific project:

npm install @n0zer0d4y/vulcan-file-ops

Prerequisites

Node.js (version 14 or higher) must be installed on your system. This provides npm and npx, which are required to run this package.

• Download Node.js: https://nodejs.org/
• Check installation: Run node --version and npm --version

Dependencies

The server has no external service dependencies and operates entirely locally. All required packages are automatically downloaded when using npx.

Usage

This server can be used directly with npx (recommended) or installed globally/locally. The npx approach requires no installation and always uses the latest version.

Basic Configuration

Add to your MCP client configuration.

For JSON-based clients such as Claude Desktop and Cursor, use their mcpServers JSON format. For Codex, use C:\Users\\.codex\config.toml and the mcp_servers TOML table format shown below.

Option 1: Using npx (Recommended - No Installation Required)

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

Codex (config.toml)

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

Option 2: Using Global Installation

After running npm install -g @n0zer0d4y/vulcan-file-ops:

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

Option 3: Using Local Installation

After running npm install @n0zer0d4y/vulcan-file-ops in 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

Then configure your MCP client:

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

Codex (config.toml)

[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, prefer node dist/cli.js with an absolute path. This works reliably in Codex and avoids PATH ambiguity.

Advanced Configuration

Approved Folders

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

macOS/Linux (npx):

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

Windows (npx):

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

Alternative: Local Repository Execution

For users running from a cloned repository (after npm 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

Path Format Note:

• 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.

Benefits:

• 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 in register_directory and list_allowed_directories tool descriptions, ensuring AI assistants can see which directories are pre-approved and avoid redundant registration attempts

How AI Assistants See Approved Folders:

When you configure --approved-folders, the server dynamically injects this information into the tool descriptions for register_directory and list_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 call list_allowed_directories first
• ✅ 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.

Notes:

• 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 runtime register_directory tool for additional access
• MCP Roots protocol (if used by client) will replace approved folders with workspace roots

Directory Filtering

Exclude specific folders from directory listings:

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

Tool Selection

Enable only specific tool categories:

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

Or enable individual tools:

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

Combined Configuration

All configuration options can be combined:

Windows Example (npx):

{
  "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"
      ]
    }
  }
}

macOS/Linux Example (npx):

{
  "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"
      ]
    }
  }
}

Alternative: Local Repository Execution

For users running from a cloned repository (after npm 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"
      ]
    }
  }
}

Directory Registration

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 the register_directory tool to gain access, then perform operations within that directory.

API

Available Tools by Categories

Read Operations

read_file

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

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

Input:

• 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)
• lines (number, optional): Number of lines for head/tail mode
• startLine (number, optional): Start line for range mode
• endLine (number, optional): End line for range mode

**Output:*

…

Source & license

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

• Author: n0zer0d4y
• Source: n0zer0d4y/vulcan-file-ops
• License: MIT
• Homepage: https://www.npmjs.com/package/@n0zer0d4y/vulcan-file-ops?activeTab=readme

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