Model Context Protocol server for filesystem operations with dynamic directory access control, supporting read/write operations, directory management, and advanced file editing.
A Node.js server implementing the Model Context Protocol (MCP) for comprehensive filesystem operations with dynamic directory access control.
This MCP server provides AI agents with secure, controlled access to filesystem operations including reading/writing files, directory management, file search, and advanced text editing. It implements flexible directory access control through command-line arguments or dynamic MCP Roots protocol, ensuring operations are restricted to authorized directories only.
The server uses two methods for specifying allowed directories:
```bash
mcp-server-filesystem /path/to/dir1 /path/to/dir2
```
Clients supporting the Roots protocol can dynamically update allowed directories at runtime via `roots/list_changed` notifications, providing a modern, flexible integration experience.
**Important**: Server requires at least ONE allowed directory. If started without command-line arguments AND client doesn't support roots protocol (or provides empty roots), initialization will fail.
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"filesystem": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
"--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
"mcp/filesystem",
"/projects"
]
}
}
}
```
**Note**: All directories must be mounted to `/projects`. Add `ro` flag for read-only access.
```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/Desktop",
"/path/to/other/allowed/dir"
]
}
}
}
```
Add to `.vscode/mcp.json` or user MCP configuration:
```json
{
"servers": {
"filesystem": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
"mcp/filesystem",
"/projects"
]
}
}
}
```
```json
{
"servers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"${workspaceFolder}"
]
}
}
}
```
**read_text_file** - Read complete file contents as UTF-8 text
**read_media_file** - Read image or audio file as base64
**read_multiple_files** - Read multiple files simultaneously
**list_directory** - List directory contents with [FILE]/[DIR] prefixes
**list_directory_with_sizes** - List directory with file sizes and statistics
**directory_tree** - Get recursive JSON tree structure
**search_files** - Recursively search with glob patterns
**get_file_info** - Get detailed metadata
**list_allowed_directories** - List all accessible directories
**write_file** - Create new file or overwrite existing (Destructive, Idempotent)
**edit_file** - Selective edits with pattern matching (Destructive, Non-idempotent)
**create_directory** - Create directory with parents if needed (Idempotent)
**move_file** - Move or rename files/directories (Non-idempotent)
When using this MCP server, follow these guidelines:
1. **Check Allowed Directories First**: Use `list_allowed_directories` to confirm access scope before performing operations
2. **Use Dry Run for Edits**: ALWAYS call `edit_file` with `dryRun: true` first to preview changes before applying them
3. **Handle Relative Paths**: All paths must be absolute or relative to allowed directories
4. **Batch Operations**: Use `read_multiple_files` instead of multiple `read_text_file` calls for efficiency
5. **Safety Checks**: Respect MCP tool annotations:
- Read-only tools are safe to call repeatedly
- Idempotent tools can be retried with same arguments
- Destructive tools require extra caution
6. **Search Best Practices**: Use `excludePatterns` to skip node_modules, .git, and other irrelevant directories
7. **Error Handling**: Failed operations in `read_multiple_files` won't stop entire operation—check individual results
```javascript
// Check accessible directories
await use_mcp_tool("filesystem", "list_allowed_directories", {});
// Search for TypeScript files excluding node_modules
await use_mcp_tool("filesystem", "search_files", {
path: "/projects/workspace",
pattern: "**/*.ts",
excludePatterns: ["**/node_modules/**", "**/.git/**"]
});
// Preview edits before applying (ALWAYS do this first)
await use_mcp_tool("filesystem", "edit_file", {
path: "/projects/workspace/src/app.ts",
edits: [
{ oldText: "const port = 3000", newText: "const port = 8080" }
],
dryRun: true
});
// Apply edits after preview
await use_mcp_tool("filesystem", "edit_file", {
path: "/projects/workspace/src/app.ts",
edits: [
{ oldText: "const port = 3000", newText: "const port = 8080" }
],
dryRun: false
});
```
MIT License
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/filesystem-mcp-server/raw