AgentAlley

Skills · Data & AI · Agent

Filesystem MCP Server

Unverified●26/40

Originally by modelcontextprotocol · MIT

Claude Code·UnknownFrontmatter could not be read
Cursor·UnknownWe have not crawled the repo tree, so we will not guess
Codex·UnknownWe have not crawled the repo tree, so we will not guess
Gemini CLI·UnknownThe spec defines no detection rule for Gemini
Copilot·UnknownWe have not crawled the repo tree, so we will not guess
npx agentalley add filesystem

This command does not work yet — the CLI is still being built. Until then, use Raw in the reader below to take the file.

Who is stuck, and on what

The whole source

No sign-in, no blur, nothing truncated
filesystem/SKILL.md366 lines14.7 KBRawView on GitHub
Frontmatter: no frontmatter — costs points on criterion B3.
1# Filesystem MCP ServerA5 — No allowed-tools declared — no way to tell what this skill may touchB3 — Frontmatter: no frontmatter
2 
3Node.js server implementing Model Context Protocol (MCP) for filesystem operations.
4 
5Published on npm as [`@modelcontextprotocol/server-filesystem`](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem).
6 
7## Features
8 
9- Read/write files
10- Create/list/delete directories
11- Move files/directories
12- Search files
13- Get file metadata
14- Dynamic directory access control via [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots)
15 
16## Directory Access Control
17 
18The server uses a flexible directory access control system. Directories can be specified via command-line arguments or dynamically via [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots).
19 
20### Method 1: Command-line Arguments
21Specify Allowed directories when starting the server:
22```bash
23mcp-server-filesystem /path/to/dir1 /path/to/dir2
24```
25 
26### Method 2: MCP Roots (Recommended)
27MCP clients that support [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots) can dynamically update the Allowed directories.
28 
29Roots notified by Client to Server, completely replace any server-side Allowed directories when provided.
30 
31**Important**: If server starts without command-line arguments AND client doesn't support roots protocol (or provides empty roots), the server will throw an error during initialization.
32 
33This is the recommended method, as this enables runtime directory updates via `roots/list_changed` notifications without server restart, providing a more flexible and modern integration experience.
34 
35### How It Works
36 
37The server's directory access control follows this flow:
38 
391. **Server Startup**
40 - Server starts with directories from command-line arguments (if provided)
41 - If no arguments provided, server starts with empty allowed directories
42 
432. **Client Connection & Initialization**
44 - Client connects and sends `initialize` request with capabilities
45 - Server checks if client supports roots protocol (`capabilities.roots`)
46
473. **Roots Protocol Handling** (if client supports roots)
48 - **On initialization**: Server requests roots from client via `roots/list`
49 - Client responds with its configured roots
50 - Server replaces ALL allowed directories with client's roots
51 - **On runtime updates**: Client can send `notifications/roots/list_changed`
52 - Server requests updated roots and replaces allowed directories again
53 
544. **Fallback Behavior** (if client doesn't support roots)
55 - Server continues using command-line directories only
56 - No dynamic updates possible
57 
585. **Access Control**
59 - All filesystem operations are restricted to allowed directories
60 - Use `list_allowed_directories` tool to see current directories
61 - Server requires at least ONE allowed directory to operate
62 
63**Note**: The server will only allow operations within directories specified either via `args` or via Roots.
64 
65 
66 
67## API
68 
69### Tools
70 
71- **read_text_file**
72 - Read complete contents of a file as text
73 - Inputs:
74 - `path` (string)
75 - `head` (number, optional): First N lines
76 - `tail` (number, optional): Last N lines
77 - Always treats the file as UTF-8 text regardless of extension
78 - Cannot specify both `head` and `tail` simultaneously
79 
80- **read_media_file**
81 - Read a file and return it as a base64-encoded content block with its MIME type
82 - Inputs:
83 - `path` (string)
84 - Streams the file and returns base64 data with the corresponding MIME type. Image and
85 audio files are returned as `image`/`audio` content; any other file type is returned as
86 an embedded `resource` (a valid MCP content block for arbitrary binary data)
87 
88- **read_multiple_files**
89 - Read multiple files simultaneously
90 - Input: `paths` (string[])
91 - Failed reads won't stop the entire operation
92 
93- **write_file**
94 - Create new file or overwrite existing (exercise caution with this)
95 - Inputs:
96 - `path` (string): File location
97 - `content` (string): File content
98 
99- **edit_file**
100 - Make selective edits using advanced pattern matching and formatting
101 - Features:
102 - Line-based and multi-line content matching
103 - Whitespace normalization with indentation preservation
104 - Multiple simultaneous edits with correct positioning
105 - Indentation style detection and preservation
106 - Git-style diff output with context
107 - Preview changes with dry run mode
108 - Inputs:
109 - `path` (string): File to edit
110 - `edits` (array): List of edit operations
111 - `oldText` (string): Text to search for (can be substring)
112 - `newText` (string): Text to replace with
113 - `dryRun` (boolean): Preview changes without applying (default: false)
114 - Returns detailed diff and match information for dry runs, otherwise applies changes
115 - Best Practice: Always use dryRun first to preview changes before applying them
116 
117- **create_directory**
118 - Create new directory or ensure it exists
119 - Input: `path` (string)
120 - Creates parent directories if needed
121 - Succeeds silently if directory exists
122 
123- **list_directory**
124 - List directory contents with [FILE] or [DIR] prefixes
125 - Input: `path` (string)
126 
127- **list_directory_with_sizes**
128 - List directory contents with [FILE] or [DIR] prefixes, including file sizes
129 - Inputs:
130 - `path` (string): Directory path to list
131 - `sortBy` (string, optional): Sort entries by "name" or "size" (default: "name")
132 - Returns detailed listing with file sizes and summary statistics
133 - Shows total files, directories, and combined size
134 
135- **move_file**
136 - Move or rename files and directories
137 - Inputs:
138 - `source` (string)
139 - `destination` (string)
140 - Fails if destination exists
141 
142- **search_files**
143 - Recursively search for files/directories that match or do not match patterns
144 - Inputs:
145 - `path` (string): Starting directory
146 - `pattern` (string): Search pattern
147 - `excludePatterns` (string[]): Exclude any patterns.
148 - Glob-style pattern matching
149 - Returns full paths to matches
150 
151- **directory_tree**
152 - Get recursive JSON tree structure of directory contents
153 - Inputs:
154 - `path` (string): Starting directory
155 - `excludePatterns` (string[]): Exclude any patterns. Glob formats are supported.
156 - Returns:
157 - JSON array where each entry contains:
158 - `name` (string): File/directory name
159 - `type` ('file'|'directory'): Entry type
160 - `children` (array): Present only for directories
161 - Empty array for empty directories
162 - Omitted for files
163 - Output is formatted with 2-space indentation for readability
164
165- **get_file_info**
166 - Get detailed file/directory metadata
167 - Input: `path` (string)
168 - Returns:
169 - Size
170 - Creation time
171 - Modified time
172 - Access time
173 - Type (file/directory)
174 - Permissions
175 
176- **list_allowed_directories**
177 - List all directories the server is allowed to access
178 - No input required
179 - Returns:
180 - Directories that this server can read/write from
181 
182### Tool annotations (MCP hints)
183 
184This server sets [MCP ToolAnnotations](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#toolannotations)
185on each tool so clients can:
186 
187- Distinguish **read‑only** tools from write‑capable tools.
188- Understand which write operations are **idempotent** (safe to retry with the same arguments).
189- Highlight operations that may be **destructive** (overwriting or heavily mutating data).
190- Signal that a tool does **not** reach an open or external world (every filesystem tool sets `openWorldHint: false`).
191 
192The mapping for filesystem tools is:
193 
194| Tool | readOnlyHint | idempotentHint | destructiveHint | Notes |
195|-----------------------------|--------------|----------------|-----------------|--------------------------------------------------|
196| `read_text_file` | `true` | – | – | Pure read |
197| `read_media_file` | `true` | – | – | Pure read |
198| `read_multiple_files` | `true` | – | – | Pure read |
199| `list_directory` | `true` | – | – | Pure read |
200| `list_directory_with_sizes` | `true` | – | – | Pure read |
201| `directory_tree` | `true` | – | – | Pure read |
202| `search_files` | `true` | – | – | Pure read |
203| `get_file_info` | `true` | – | – | Pure read |
204| `list_allowed_directories` | `true` | – | – | Pure read |
205| `create_directory` | `false` | `true` | `false` | Re‑creating the same dir is a no‑op |
206| `write_file` | `false` | `true` | `true` | Overwrites existing files |
207| `edit_file` | `false` | `false` | `true` | Re‑applying edits can fail or double‑apply |
208| `move_file` | `false` | `false` | `true` | Deletes source file |
209 
210> Note: `idempotentHint` and `destructiveHint` are meaningful only when `readOnlyHint` is `false`, as defined by the MCP spec. Every tool also sets `openWorldHint: false` — this server only accesses the local filesystem within its allowed directories, never an open or external world.
211 
212## Usage with Claude Desktop
213Add this to your `claude_desktop_config.json`:
214 
215Note: you can provide sandboxed directories to the server by mounting them to `/projects`. Adding the `ro` flag will make the directory readonly by the server.
216 
217### Docker
218Note: all directories must be mounted to `/projects` by default.
219 
220```json
221{
222 "mcpServers": {
223 "filesystem": {
224 "command": "docker",
225 "args": [
226 "run",
227 "-i",
228 "--rm",
229 "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
230 "--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
231 "--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
232 "mcp/filesystem",
233 "/projects"
234 ]
235 }
236 }
237}
238```
239 
240### NPX
241 
242```json
243{
244 "mcpServers": {
245 "filesystem": {
246 "command": "npx",
247 "args": [
248 "-y",
249 "@modelcontextprotocol/server-filesystem",
250 "/Users/username/Desktop",
251 "/path/to/other/allowed/dir"
252 ]
253 }
254 }
255}
256```
257 
258On Windows, use `cmd /c` to launch `npx`:
259 
260```json
261{
262 "mcpServers": {
263 "filesystem": {
264 "command": "cmd",
265 "args": [
266 "/c",
267 "npx",
268 "-y",
269 "@modelcontextprotocol/server-filesystem",
270 "/Users/username/Desktop",
271 "/path/to/other/allowed/dir"
272 ]
273 }
274 }
275}
276```
277 
278## Usage with VS Code
279 
280For quick installation, click the installation buttons below...
281 
282[![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-NPM-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-filesystem%22%2C%22%24%7BworkspaceFolder%7D%22%5D%7D) [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-NPM-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modelcontextprotocol%2Fserver-filesystem%22%2C%22%24%7BworkspaceFolder%7D%22%5D%7D&quality=insiders)B1 — Line is 750 characters — unreadable by eye
283 
284[![Install with Docker in VS Code](https://img.shields.io/badge/VS_Code-Docker-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22--mount%22%2C%22type%3Dbind%2Csrc%3D%24%7BworkspaceFolder%7D%2Cdst%3D%2Fprojects%2Fworkspace%22%2C%22mcp%2Ffilesystem%22%2C%22%2Fprojects%22%5D%7D) [![Install with Docker in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Docker-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22--mount%22%2C%22type%3Dbind%2Csrc%3D%24%7BworkspaceFolder%7D%2Cdst%3D%2Fprojects%2Fworkspace%22%2C%22mcp%2Ffilesystem%22%2C%22%2Fprojects%22%5D%7D&quality=insiders)B1 — Line is 940 characters — unreadable by eye
285 
286For manual installation, you can configure the MCP server using one of these methods:
287 
288**Method 1: User Configuration (Recommended)**
289Add the configuration to your user-level MCP configuration file. Open the Command Palette (`Ctrl + Shift + P`) and run `MCP: Open User Configuration`. This will open your user `mcp.json` file where you can add the server configuration.
290 
291**Method 2: Workspace Configuration**
292Alternatively, you can add the configuration to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
293 
294> For more details about MCP configuration in VS Code, see the [official VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).
295 
296You can provide sandboxed directories to the server by mounting them to `/projects`. Adding the `ro` flag will make the directory readonly by the server.
297 
298### Docker
299Note: all directories must be mounted to `/projects` by default.
300 
301```json
302{
303 "servers": {
304 "filesystem": {
305 "command": "docker",
306 "args": [
307 "run",
308 "-i",
309 "--rm",
310 "--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
311 "mcp/filesystem",
312 "/projects"
313 ]
314 }
315 }
316}
317```
318 
319### NPX
320 
321```json
322{
323 "servers": {
324 "filesystem": {
325 "command": "npx",
326 "args": [
327 "-y",
328 "@modelcontextprotocol/server-filesystem",
329 "${workspaceFolder}"
330 ]
331 }
332 }
333}
334```
335 
336On Windows, use:
337 
338```json
339{
340 "servers": {
341 "filesystem": {
342 "command": "cmd",
343 "args": [
344 "/c",
345 "npx",
346 "-y",
347 "@modelcontextprotocol/server-filesystem",
348 "${workspaceFolder}"
349 ]
350 }
351 }
352}
353```
354 
355## Build
356 
357Docker build:
358 
359```bash
360docker build -t mcp/filesystem -f src/filesystem/Dockerfile .
361```
362 
363## License
364 
365This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
366 

Reviews

Installed this one?Write the first review and take the Trailblazer badge.

Reviews only open after a real install, so this is empty — and we leave it empty rather than invent one.

Alternatives

Also in Data & AI
Task Coordination StrategiesDecompose complex tasks, design dependency graphs, and coordinate multi-agent work with proper task descriptions and workload balancing. Use this skill when breaking down work for agent teams, managing task dependencies, or monitoring team progress.Data & AI · MIT◐◐◐◐◐●35/40Ebay Seller ToolsData & AI · MIT·····●34/40Tough Decision Advisor: Every Angle ConsideredHand in a decision you're stuck on. Get back a clear breakdown of every angle — the trade-offs, the risks, the blind spot, and a recommended path.Data & AI · Business · MIT license●····●32/40DHDNA Profiler — Cognitive Pattern ExtractionPaste any email, proposal, or note someone wrote, and get back a plain-language read on how they think, what drives their decisions, and how they communicate.Data & AI · Research & analysis · MIT license●····●32/40