@ai-capabilities-suite/mcp-filesystem
Advanced tools
MCP server for advanced filesystem operations with strict security boundaries. Batch operations, directory watching, file search/indexing, and permission management - all within secure, configurable boundaries.
Advanced filesystem operations for AI agents with strict security boundaries. Part of the AI Capabilities Suite.
This package is maintained in the AI Capabilities Suite monorepo.
The MCP Filesystem Server provides AI agents with advanced file operations beyond basic read/write, including:
All operations are confined within strict security boundaries to prevent unauthorized access.
CRITICAL: This server implements defense-in-depth security with 10 layers of path validation. All operations are confined to a configured workspace root. See SECURITY.md for complete security documentation.
npm install -g @ai-capabilities-suite/mcp-filesystem
yarn global add @ai-capabilities-suite/mcp-filesystem
docker pull ghcr.io/digital-defiance/mcp-filesystem:latest
See DOCKER.md for Docker deployment guide.
Create a mcp-filesystem-config.json file:
{
"workspaceRoot": "/path/to/your/workspace",
"blockedPaths": [".git", ".env", "node_modules"],
"blockedPatterns": ["*.key", "*.pem", "*.env"],
"maxFileSize": 104857600,
"maxBatchSize": 1073741824,
"maxOperationsPerMinute": 100,
"enableAuditLog": true,
"readOnly": false
}
mcp-filesystem --config ./mcp-filesystem-config.json
Add to your MCP client configuration (e.g., Claude Desktop, Kiro):
{
"mcpServers": {
"filesystem": {
"command": "mcp-filesystem",
"args": ["--config", "/path/to/mcp-filesystem-config.json"]
}
}
}
The server exposes 12 MCP tools for filesystem operations:
Execute multiple filesystem operations atomically with rollback support.
Parameters:
operations: Array of operations (copy, move, delete)atomic: Boolean (default: true) - rollback all on failureExample:
{
"operations": [
{ "type": "copy", "source": "file1.txt", "destination": "backup/file1.txt" },
{ "type": "move", "source": "temp.txt", "destination": "archive/temp.txt" },
{ "type": "delete", "source": "old.txt" }
],
"atomic": true
}
Monitor a directory for filesystem changes.
Parameters:
path: Directory to watchrecursive: Boolean - watch subdirectoriesfilters: Array of glob patterns to filter eventsReturns: Session ID for retrieving events
Example:
{
"path": "src",
"recursive": true,
"filters": ["*.ts", "*.js"]
}
Retrieve accumulated events from a watch session.
Parameters:
sessionId: Watch session ID from fs_watch_directoryReturns: Array of filesystem events (create, modify, delete, rename)
Stop a directory watch session and clean up resources.
Parameters:
sessionId: Watch session ID to stopSearch for files by name, content, or metadata.
Parameters:
query: Search query stringsearchType: "name", "content", or "both"fileTypes: Array of file extensions to filterminSize, maxSize: Size constraints in bytesmodifiedAfter: ISO date stringuseIndex: Boolean - use file index for faster searchExample:
{
"query": "TODO",
"searchType": "content",
"fileTypes": [".ts", ".js"],
"useIndex": true
}
Build a searchable index of files for fast searching.
Parameters:
path: Directory to indexincludeContent: Boolean - index file contents (text files only)Returns: Index statistics (file count, total size, index size)
Create a symbolic link within the workspace.
Parameters:
linkPath: Path where symlink will be createdtargetPath: Path the symlink points to (must be within workspace)Compute file checksum for integrity verification.
Parameters:
path: File pathalgorithm: "md5", "sha1", "sha256", or "sha512"Returns: Checksum hex string
Verify a file's checksum matches expected value.
Parameters:
path: File pathchecksum: Expected checksum hex stringalgorithm: Hash algorithm usedReturns: Boolean verification result
Analyze disk usage and identify large files/directories.
Parameters:
path: Directory to analyzedepth: Maximum depth to traversegroupByType: Boolean - group results by file extensionReturns: Usage report with sizes, largest files, and type breakdown
Recursively copy a directory with options.
Parameters:
source: Source directorydestination: Destination directorypreserveMetadata: Boolean - preserve timestamps and permissionsexclusions: Array of glob patterns to excludeReturns: Copy statistics (files copied, bytes transferred, duration)
Sync directories by copying only newer or missing files.
Parameters:
source: Source directorydestination: Destination directoryexclusions: Array of glob patterns to excludeReturns: Sync statistics (files copied, files skipped, bytes transferred)
allowedSubdirectories: Array of subdirectories within workspace (optional)
["src", "tests", "docs"]blockedPaths: Array of paths to block (relative to workspace)
[".git", ".env", "node_modules", ".ssh"]blockedPatterns: Array of regex patterns to block
["*.key", "*.pem", "*.env", "*secret*", "*password*"]The server implements 10 layers of path validation:
.. and ./ sequencesSystem Paths (Always Blocked):
/etc, /sys, /proc, /dev, /boot, /rootC:\Windows, C:\Program Files/System, /Library, /Applications (macOS)/bin, /sbin, /usr/bin, /usr/sbinSensitive Patterns (Always Blocked):
.ssh/, .aws/, .kube/id_rsa, *.pem, *.key, *.p12, *.pfxpassword, secret, token.env filesAll operations are logged with:
// Copy multiple files atomically
const result = await mcpClient.callTool("fs_batch_operations", {
operations: [
{ type: "copy", source: "src/file1.ts", destination: "backup/file1.ts" },
{ type: "copy", source: "src/file2.ts", destination: "backup/file2.ts" },
{ type: "copy", source: "src/file3.ts", destination: "backup/file3.ts" },
],
atomic: true, // All succeed or all rollback
});
// Start watching
const watchResult = await mcpClient.callTool("fs_watch_directory", {
path: "src",
recursive: true,
filters: ["*.ts", "*.tsx"],
});
const sessionId = watchResult.sessionId;
// Later, get events
const events = await mcpClient.callTool("fs_get_watch_events", {
sessionId,
});
// Stop watching
await mcpClient.callTool("fs_stop_watch", { sessionId });
// Build index first
await mcpClient.callTool("fs_build_index", {
path: "src",
includeContent: true,
});
// Fast search using index
const results = await mcpClient.callTool("fs_search_files", {
query: "TODO",
searchType: "content",
fileTypes: [".ts", ".js"],
useIndex: true,
});
// Compute checksum
const checksumResult = await mcpClient.callTool("fs_compute_checksum", {
path: "important-file.zip",
algorithm: "sha256",
});
// Later, verify integrity
const verifyResult = await mcpClient.callTool("fs_verify_checksum", {
path: "important-file.zip",
checksum: checksumResult.checksum,
algorithm: "sha256",
});
// Sync only newer/missing files
const syncResult = await mcpClient.callTool("fs_sync_directory", {
source: "src",
destination: "backup",
exclusions: ["*.test.ts", "node_modules/**"],
});
console.log(
`Copied: ${syncResult.filesCopied}, Skipped: ${syncResult.filesSkipped}`
);
Cause: Attempting to access files outside the configured workspace root.
Solution:
workspaceRoot configuration is correct.. sequences in pathsCause: Attempting to access hardcoded system paths.
Solution: These paths are always blocked for security. Configure your workspace to avoid system directories.
Cause: Attempting to access files matching sensitive patterns (.ssh/, *.key, etc.).
Solution: These patterns are always blocked. If you need to access these files, they must be renamed or moved outside sensitive patterns.
Cause: Too many operations in a short time period.
Solution:
maxOperationsPerMinute in configurationfs_batch_operationsCause: File size exceeds maxFileSize configuration.
Solution: Increase maxFileSize in configuration or split large files.
Cause: Events may be filtered or watch session not active.
Solution:
sessionIdfilters parameter - ensure patterns match your filesrecursive setting)Cause: Index may be outdated or search parameters too restrictive.
Solution:
fs_build_indexfileTypes filter isn't excluding your filesquery matches file content/namesuseIndex: false for filesystem searchCause: Symlink target is outside workspace.
Solution: All symlink targets must be within the workspace root. This is a security requirement and cannot be disabled.
fs_build_index for faster searchesfs_batch_operations instead of individual operationsfileTypes and size filters to narrow search resultsfs_sync_directory instead of full copy when possiblegit clone https://github.com/Digital-Defiance/ai-capabilities-suite.git
cd ai-capabilities-suite/packages/mcp-filesystem
yarn install
yarn build
yarn test # Run all tests
yarn test:coverage # Run with coverage
yarn test:watch # Watch mode
yarn build
node dist/cli.js --config ./config.json
Contributions are welcome! Please see CONTRIBUTING.md in the root repository.
MIT License - see LICENSE for details.
Built with:
FAQs
MCP server for advanced filesystem operations with strict security boundaries. Batch operations, directory watching, file search/indexing, and permission management - all within secure, configurable boundaries.
We found that @ai-capabilities-suite/mcp-filesystem demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A malicious NuGet package impersonating Sicoob exfiltrated client IDs, PFX passwords, and banking certificates through Sentry telemetry.
Security News
Feross Aboukhadijeh joins TBPN to discuss Socket's $60M Series C, 500%+ ARR growth, AI's impact on open source, and the rise in supply chain attacks.
Security News
OSV withdrew 157 OSV malware reports after automated false positives incorrectly flagged trusted npm and PyPI packages, sending bad records into tools that rely on OSV data.