# Vulcan File Ops

> A Security-centric MCP Server providing enterprise-grade filesystem powers to AI assistants—read, write, edit, and manage files with comprehensive CVE protection and user-controlled access.. [Explore comprehensive code documentation and architecture details on DeepWiki](https://deepwiki.com/n0zer0d4y/vulcan-file-ops)

- **Type:** MCP server
- **Install:** `agentstack add mcp-n0zer0d4y-vulcan-file-ops`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [n0zer0d4y](https://agentstack.voostack.com/s/n0zer0d4y)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [n0zer0d4y](https://github.com/n0zer0d4y)
- **Source:** https://github.com/n0zer0d4y/vulcan-file-ops
- **Website:** https://www.npmjs.com/package/@n0zer0d4y/vulcan-file-ops?activeTab=readme

## Install

```sh
agentstack add mcp-n0zer0d4y-vulcan-file-ops
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)
    - [read_file](#read_file)
    - [attach_image](#attach_image)
    - [read_multiple_files](#read_multiple_files)
  - [Write Operations](#write-operations)
    - [write_file](#write_file)
    - [write_multiple_files](#write_multiple_files)
    - [edit_file](#edit_file)
  - [Filesystem Operations](#filesystem-operations)
    - [make_directory](#make_directory)
    - [list_directory](#list_directory)
    - [move_file](#move_file)
    - [file_operations](#file_operations)
    - [delete_files](#delete_files)
    - [get_file_info](#get_file_info)
    - [register_directory](#register_directory)
    - [list_allowed_directories](#list_allowed_directories)
  - [Search Operations](#search-operations)
    - [glob_files](#glob_files)
    - [grep_files](#grep_files)
  - [Shell Operations](#shell-operations)
    - [execute_shell](#execute_shell)
- [Security](#security)
- [Contributing](#contributing)
- [License](#license)

## Background

### Model Context Protocol

The [Model Context Protocol](https://modelcontextprotocol.io) (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 (node_modules, dist, .git) from listings as list_directory 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:

```bash
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:

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

### Local Installation

Install in a specific project:

```bash
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)

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

**Codex (`config.toml`)**

```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`:

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

#### Option 3: Using Local Installation

After running `npm install @n0zer0d4y/vulcan-file-ops` in your project:

```json
{
  "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:

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

Then configure your MCP client:

```json
{
  "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`)**

```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):**

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

**Windows (npx):**

```json
{
  "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`):

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

**Codex with Approved Folders (`config.toml`)**

```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:

```json
{
  "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:

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

Or enable individual tools:

```json
{
  "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):**

```json
{
  "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):**

```json
{
  "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`):

```json
{
  "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](https://github.com/n0zer0d4y)
- **Source:** [n0zer0d4y/vulcan-file-ops](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-n0zer0d4y-vulcan-file-ops
- Seller: https://agentstack.voostack.com/s/n0zer0d4y
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.