A community-driven registry for Claude, Cursor, Windsurf, Cline & more. Not affiliated with Anthropic.
Are you the author? Sign in to claim
A Security-centric MCP Server providing enterprise-grade filesystem powers to AI assistants—read, write, edit, and manag
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.
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.
This enhanced implementation provides:
This server supports multiple flexible approaches to directory access:
--approved-folders to specify directories on server start for immediate accessregister_directory toolThis 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.
Run directly without installation:
npx @n0zer0d4y/vulcan-file-ops --help
For developers who want to contribute or modify the code, see Local Repository Execution below.
Install globally for system-wide access:
npm install -g @n0zer0d4y/vulcan-file-ops
Install in a specific project:
npm install @n0zer0d4y/vulcan-file-ops
Node.js (version 14 or higher) must be installed on your system. This provides npm and npx, which are required to run this package.
node --version and npm --versionThe server has no external service dependencies and operates entirely locally. All required packages are automatically downloaded when using npx.
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.
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\<username>\.codex\config.toml and the mcp_servers TOML table format shown below.
{
"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
After running npm install -g @n0zer0d4y/vulcan-file-ops:
{
"mcpServers": {
"vulcan-file-ops": {
"command": "vulcan-file-ops"
}
}
}
After running npm install @n0zer0d4y/vulcan-file-ops in your project:
{
"mcpServers": {
"vulcan-file-ops": {
"command": "./node_modules/.bin/vulcan-file-ops"
}
}
}
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.
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:
C:/, D:/). Use forward slashes in JSON to avoid escaping backslashes./ for absolute paths, or use ~ for home directory.Benefits:
register_directory and list_allowed_directories tool descriptions, ensuring AI assistants can see which directories are pre-approved and avoid redundant registration attemptsHow 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:
list_allowed_directories firstExample 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:
C:/path), Unix/Mac starts with / or ~register_directory tool for additional accessExclude specific folders from directory listings:
{
"mcpServers": {
"vulcan-file-ops": {
"command": "npx",
"args": [
"@n0zer0d4y/vulcan-file-ops",
"--ignored-folders",
"node_modules,dist,.git,.next"
]
}
}
}
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"
]
}
}
}
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"
]
}
}
}
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.
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 pathmode (string, optional): Read mode
full - Read entire file (default)head - Read first N linestail - Read last N linesrange - Read arbitrary line range (e.g., lines 50-100)lines (number, optional): Number of lines for head/tail modestartLine (number, optional): Start line for range modeendLine (number, optional): End line for range modeOutput: File contents as text. Supports text files and documents (PDF, DOCX, PPTX, XLSX, ODT, ODP, ODS)
Attach images for AI vision analysis
Input:
path (string | string[]): Path to image file, or array of paths to attach multiple images at onceOutput: Image content in MCP format for vision model processing. Supports PNG, JPEG, GIF, WebP, BMP, SVG
Batch read multiple files concurrently
Input:
files (array): List of file objects with path and optional mode settingsOutput: Contents of all files. Failed reads don't stop the operation
Create or replace file content
Note: This tool is limited to single-file operations only. RECOMMENDED: Use write_multiple_files instead, which supports both single and batch file operations for greater flexibility.
Automatic directory creation:
Input:
path (string): File pathcontent (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
Automatic directory creation:
Input:
files (array): List of file objects with path and contentOutput: 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 pathedits (array): List of edit operations, each containing:
oldText (string): Text to search for (include 3-5 lines of context)newText (string): Text to replace withinstruction (string, optional): Description of what this edit doesexpectedOccurrences (number, optional): Expected match count (default: 1)matchingStrategy (string, optional): Matching strategy
exact - Character-for-character match (fastest, safest)flexible - Whitespace-insensitive matching, preserves indentationfuzzy - Token-based regex matching (most permissive)auto - Try exact → flexible → fuzzy (default)dryRun (boolean, optional): Preview changes without writing (default: false)failOnAmbiguous (boolean, optional): Fail when matches are ambiguous (default: true)Multi-File Input (mode: 'multiple'):
mode (string): Set to "multiple"files (array): Array of file edit requests (max 50), each containing:
path (string): File pathedits (array): List of edit operations for this file (same structure as above)matchingStrategy (string, optional): Per-file matching strategydryRun (boolean, optional): Per-file dry-run modefailOnAmbiguous (boolean, optional): Per-file ambiguity handlingfailFast (boolean, optional): Stop on first failure with rollback (true, default) or continue (false)Features:
Output: Detailed diff with statistics. For multi-file operations, includes per-file results and summary statistics with rollback information for atomic operations.
Important: Use actual newline characters in oldText/newText, NOT escape sequences like \n.
Create single or multiple directories (like Unix mkdir -p)
Input:
paths (string | array): Single path or array of pathsOutput: Success confirmation. Creates parent directories recursively, idempotent
List directory contents with multiple output formats
Input:
path (string): Directory pathformat (string, optional): Output format
simple - Basic [DIR]/[FILE] listing (default)detailed - With sizes, timestamps, and statisticstree - Hierarchical text tree viewjson - Structured data with full metadatasortBy (string, optional): Sort order
name - Alphabetical (default)size - Largest firstexcludePatterns (array, optional): Glob patterns to exclude (e.g., ['*.log', 'temp*'])Output: Directory listing in specified format with metadata
Relocate or rename files and directories
Note: This tool is limited to single-file operations only. RECOMMENDED: Use file_operations instead, which supports move, copy, and rename operations for both single and batch files with greater flexibility.
Input:
source (string): Source pathdestination (string): Destination pathOutput: Success confirmation
Bulk file operations (move, copy, rename)
Input:
operation (string): Operation type
move - Relocate filescopy - Duplicate filesrename - Rename filesfiles (array): List of source-destination pairsonConflict (string, optional): Conflict resolution
skip - Skip existing filesoverwrite - Replace existing fileserror - Fail on conflicts (default)Output: Status for each operation. Maximum 100 files per operation
Delete single or multiple files and directories
Input:
paths (array): List of paths to deleterecursive (boolean, optional): Enable recursive deletionforce (boolean, optional): Force delete read-only filesOutput: Status for each deletion. Non-recursive by default for safety
Retrieve file and directory metadata
Input:
path (string): File or directory pathOutput: Size, timestamps, permissions, and type information
Enable runtime access to new directories
Input:
path (string): Directory path to registerOutput: Success confirmation. Directory becomes accessible for operations
Display currently accessible directory paths
Input: None
Output: List of all allowed directories
Find files using glob pattern matching
Input:
path (string): Directory to searchpattern (string): Glob pattern (e.g., **/*.ts)excludePatterns (array, optional): Patterns to excludeOutput: List of matching file paths
Search for text patterns within files
Input:
pattern (string): Regex pattern to searchpath (string, optional): Directory to search-i (boolean, optional): Case insensitive-A/-B/-C (number, optional): Context lines before/after matchestype (string, optional): File type filter (js, py, ts, etc.)output_mode (string, optional): Output format
content - Matching lines with line numbers (default)files_with_matches - File paths onlycount - Match counts per filehead_limit (number, optional): Limit resultsOutput: Matching lines with context, file paths, or match counts
Execute shell commands with security controls
Input:
command (string): Shell command to executedescription (string, optional): Command purposeworkdir (string, optional): Working directory (must be within allowed directories). If not provided, process.cwd() is used and validatedtimeout (number, optional): Timeout in milliseconds (default: 30000)Output: Exit code, stdout, stderr, and execution metadata
Security:
Batch refactor across multiple files:
{
files: [
{
path: "src/utils.ts",
edits: [{
instruction: "Update deprecated function call",
oldText: "oldApi.getData()",
newText: "newApi.fetchData()"
}]
},
{
path: "src/components/Button.tsx",
edits: [{
instruction: "Update component prop",
oldText: "onClick={oldHandler}",
newText: "onClick={newHandler}"
}]
},
{
path: "src/hooks/useData.ts",
edits: [{
instruction: "Update hook implementation",
oldText: "const data = oldApi.getData()",
newText: "const data = newApi.fetchData()"
}]
}
],
failFast: true // Atomic operation - rollback all if any fails
}
Per-file configuration:
{
files: [
{
path: "config.json",
edits: [{
oldText: '"version": "1.0.0"',
newText: '"version": "1.1.0"'
}],
matchingStrategy: "exact" // JSON needs exact matches
},
{
path: "src/app.py",
edits: [{
oldText: "def old_function():",
newText: "def new_function():"
}],
matchingStrategy: "flexible" // Python indentation may vary
},
{
path: "README.md",
edits: [{
oldText: "## Old Section",
newText: "## New Section"
}],
matchingStrategy: "auto" // Let AI decide best strategy
}
],
failFast: false // Continue even if some files fail
}
For detailed usage examples, see Tool Usage Guide
This MCP server implements enterprise-grade security controls to protect against common filesystem vulnerabilities. All security measures are based on industry best practices and address known CVE patterns.
isPathWithinAllowedDirectories() which requires actual subdirectory paths (not just prefix matches)/path/to/allowed_evil when /path/to/allowed is approved$(), ` `, >(), <() patterns; validates all commands in chains; requires approval for dangerous operationsecho "; malicious_cmd; echo" injection attemptstype C:\Windows\System32\drivers\etc\hosts and cat /etc/passwd when these paths are outside approved directoriesexecute_shell tool - paths in arguments are validated just like filesystem operationsrealpath() before validation to follow symlinks to actual targets/etc/passwd even if symlink is in allowed directory../ traversal attempts; validates parent directories before file creation/unauthorized/path regardless of traversal attempts$(), backticks, process substitutionregister_directory tool.git, node_modules) from listings--enabled-tools or --enabled-tool-categories--approved-commands; require approval for othersThis server has been comprehensively audited against known vulnerabilities and static analysis findings:
CVE Protection Status:
Latest Security Audits:
make_directory vulnerability identified and fixedsrc/tests/Security Architecture:
Read Tools (read_file, read_multiple_files):
.pdf) - Plain text extraction via pdf-parse.docx) - Markdown with formatting (headings, bold, lists, tables) via mammoth.pptx) - Plain text extraction via officeparser.xlsx) - Plain text extraction via officeparser.odt) - Plain text extraction via officeparser.odp) - Plain text extraction via officeparser.ods) - Plain text extraction via officeparserread_file supports four modes for text files:
read_multiple_files allows per-file mode specification - each file can use a different mode in a single operationWrite Tools (write_file, write_multiple_files, edit_file):
Attach Image Tool (attach_image):
Example Usage:
# Single image
User: "Attach /screenshots/error.png and tell me what's wrong"
AI: [Analyzes image] "This screenshot shows a TypeError on line 42..."
# Multiple images at once
User: "Attach both /screenshots/before.png and /screenshots/after.png and compare them"
AI: [Analyzes both images] "The 'before' screenshot shows..., while the 'after' screenshot..."
Client Compatibility:
Note: There is currently no write capability for binary files. You can attach images for vision analysis but cannot create or modify image files through the filesystem tools.
File Operations Tool (file_operations, move_file):
Edit File Tool (edit_file):
dryRun: true)# Clone the repository
git clone https://github.com/n0zer0d4y/vulcan-file-ops.git
cd vulcan-file-ops
# Install dependencies
npm install
# Run tests
npm test
# Build the project
npm run build
# Start development server
npm start
The project includes comprehensive test coverage. Run tests with:
npm test
Pull requests are not being accepted for this project.
Bug reports and feature requests are welcome through GitHub issues. Please include:
Existing issues may already cover your topic, so please search first.
This project is licensed under the MIT License - see the LICENSE file for details.
MCP server integration for DaVinci Resolve Studio
mcp-language-server gives MCP enabled clients access semantic tools like get definition, references, rename, and diagnos
Run Claude Code as an MCP server so any agent can delegate coding tasks to it
@microsoft✓ OfficialBrowser automation using accessibility snapshots instead of screenshots