Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@file-manager-mcp list the files in src/ and read the first 50 lines of main.py"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
给 AI 助手用的沙箱文件管理器 —— 目录列表、读、写、搜索,全部锁在指定根目录内。
让 AI 碰文件系统,几乎所有事故都来自同一个根因:路径校验做在字符串上,而不是解析后的真实路径上。
用户给: ../../../../etc/passwd → 字符串前缀检查能过
用户给: data/link → /etc (符号链接) → 字符串前缀检查也能过这个服务在每次操作前先把路径 resolve()(展开符号链接、消掉 ..),再做根目录前缀比对。两个逃逸向量一起堵死。
一个真实的教训(search 的软链绕过):read/write 都做了 resolve 校验,
但最初的 search 用 os.walk + read_bytes 直接读 —— 根目录内的文件软链
指向外部时,外部文件内容被原样读出。修复:每个候选文件都先 resolve
再校验,越界跳过并在结果里报告 escape_skipped(见 git 的
fix(security) 提交和对应的回归测试)。
Related MCP server: File Manager MCP Server
边界 | 说明 |
根目录锁定 |
|
符号链接 | 解析后比对 —— 根目录内的软链指向根目录外时同样被拒(list/read/write/search 全部覆盖) |
硬链接 | resolve 对硬链接无效(路径真在根内、inode 另有名字在根外)—— 用 |
读限制 | 单文件 1 MB / 2000 行;含 NUL 字节判定为二进制,不返回乱码 |
写限制 | 单次 5 MB;可用 |
搜索限制 | 最多 200 条结果;自动跳过 .git/node_modules/pycache/.venv;越界软链/硬链跳过并计数 |
硬链接那条是对抗性验证补充的:根目录内预置的硬链接(需本地文件系统权限,
典型场景是"根目录为共享/可写目录")能穿透 read/search/write 三条路径,
resolve() 对此无能为力。修复用 O(1) 的 nlink 检测;代价是根内合法的
硬链接文件默认被拒,需要时用 MCP_ALLOW_HARDLINKS=1 放行。
pip install -e .{
"mcpServers": {
"files": {
"command": "file-manager-mcp",
"env": {
"MCP_FILE_ROOT": "/home/me/projects",
"MCP_WRITE_ENABLED": "1"
}
}
}
}多个根目录用 : 分隔(Linux/macOS)或 ;(Windows)。
list_dir(path=".", pattern="*")列目录,glob 过滤。返回名称(目录带 /)、类型、大小、修改时间。
read_file(path, offset=1, limit=0)文本读取,带行号。自动识别二进制(前 8KB 含 NUL 即判定),超 1 MB 直接拒绝而不是截断后假装成功。
write_file(path, content, append=false)写入。父目录不存在会自动创建。append=true 追加。
search(path=".", name_glob="*", content_regex="", max_results=50)双条件搜索:文件名 glob + 内容正则。同时给出时取交集。内容命中带行号和片段。
[拒绝] 路径越界。允许的根目录: /home/me/projects # ../../etc/passwd
[拒绝] 路径越界。允许的根目录: /home/me/projects # 指向外部的符号链接
[拒绝] 文件 5242880 字节,超过 1048576 字节上限(避免灌爆上下文)
[拒绝] 写操作已被禁用(MCP_WRITE_ENABLED=0)
[二进制] app.bin 含 NUL 字节,判定为二进制文件(2048 字节)不返回内容pip install -e ".[dev]"
pytest tests/ -vMIT
列出目录内容(最多 500 项)。返回名称/类型/大小/修改时间。
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | . | |
| pattern | No | * |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses a truncation limit (max 500 items) and the returned fields, which is genuine behavioral context, but says nothing about ordering, recursion into subdirectories, symlink handling, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no filler, and the core list action plus the item cap are front-loaded. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value explanation is somewhat redundant, and the tool is simple with only two optional parameters. However, the total absence of parameter semantics and usage guidance leaves meaningful gaps for how to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, yet it never mentions either the path or pattern parameter or their defaults. The parameter names are largely self-explanatory, which keeps this above 1, but the description adds essentially no meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (list directory contents) that an agent can easily distinguish from read_file, write_file, and search. It does not explicitly contrast with the sibling 'search', which can also surface file listings, but the core purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no when-to-use guidance, prerequisites, or alternatives. It never says when to prefer list_dir over search, nor how the pattern parameter interacts with listing. Usage must be entirely inferred from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
读取文本文件内容(上限 1MB / 2000 行,自动识别二进制)。
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden; it usefully discloses a 1MB/2000-line ceiling and automatic binary detection. However, it is silent on what happens when the cap is hit (truncation vs. error), how binary files are surfaced, and whether any permission constraints apply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the core action and appends constraints with no filler. Nothing could be removed without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value explanation is not required, but with three undocumented parameters and zero annotation coverage the definition leaves the offset/limit paging behavior and truncation semantics entirely to guesswork.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry parameter meaning, but it never mentions limit or offset, whose non-obvious defaults (limit=0, offset=1) beg for explanation. The stated 1MB/2000-line cap is a hard constraint, not an explanation of how those parameters control paging.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (读取文本文件内容) and adds scope details (1MB/2000 line cap, binary auto-detection). It is clearly distinct from write_file by the read/write verb, but it never contrasts itself with search or list_dir, which also surface file content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool reads a file but gives no guidance on when to prefer it over search (content lookup) or list_dir (enumeration). There are no stated prerequisites, no exclusions, and no named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
在根目录内搜索:name_glob 按文件名匹配,content_regex 按内容正则匹配。
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | . | |
| name_glob | No | * | |
| max_results | No | ||
| content_regex | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about recursion depth, permission requirements, performance, or whether the operation is read-only. The only behavioral hint is the implicit read-only nature of 'search'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence with no wasted words, but the brevity comes at the cost of under-specification rather than being earned conciseness. It is front-loaded with the core action, which is a plus.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values needn't be described, but for a 4-parameter tool with zero annotation coverage the description omits usage context, two parameter meanings, and any behavioral caveats. It is insufficient for an agent to call the tool confidently in edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it only explains two of four parameters (name_glob, content_regex). Both path (default '.') and max_results (default 50) are left completely undocumented, and the phrase 'within the root directory' arguably conflicts with the configurable path parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb (搜索结果/搜索) on a clear resource (root directory files) and distinguishes two matching modes, name_glob for filenames and content_regex for file contents. It does not differentiate itself from siblings list_dir/read_file, but the search semantics are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus list_dir, read_file, or write_file, and no mention of when a name-glob search is preferable to a content-regex search. The agent must infer usage entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
写入文本文件(新建或覆盖;append=true 追加)。仅限根目录内。
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| append | No | ||
| content | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations the description carries full burden, and it does disclose useful behavior beyond the schema: overwrite semantics, the additive append mode, and the root-directory sandbox restriction. It omits permissions, encoding, failure/error behavior and whether directory paths are auto-created, so it is only partially complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence that front-loads the action, the mode variants, and the scope constraint with no waste. Slightly telegraphic, but structurally efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need not be described. For a mutation tool with zero annotations and zero schema-description coverage, the description is adequate but leaves real gaps (path resolution rules, error behavior, overwrite confirmation) that could matter to an agent calling it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the append parameter's meaning effectively, but leaves path (relative to root? format? overwrite target resolution) and content (encoding) unelaborated. Partial compensation only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb (写入/write) and resource (文本文件/text file), and clarifies the two modes (新建或覆盖 vs append). It is readily distinguishable from read_file, list_dir and search. It stops short of a full 5 because sibling differentiation is implicit rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives the append=true trigger condition, which is the main branch point for this tool. However there is no explicit when/when-not guidance or routing to alternatives (though no write sibling exists). Usage is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0list_dirread_filesearchwrite_fileScored across 4 tools
list_dir, read_file, write_file, and search each target a clearly distinct operation (listing, reading, writing, searching) with no functional overlap. The only potential confusion is search's name_glob versus list_dir, but the descriptions make the boundary clear (global search vs. single-directory listing).
Three tools follow a clean verb_noun pattern (list_dir, read_file, write_file), while 'search' is a bare verb, a minor deviation from the otherwise consistent convention. Still highly readable and predictable.
Four tools cover core file operations without redundancy, and each earns its place. It is on the lean side for a 'file-manager' but still within a reasonable scope.
Core read, write, list, and search are covered, but a file manager is missing delete, move/rename, and copy/mkdir operations. These are notable gaps that limit real management workflows.
Safe folder access for ChatGPT and Claude: read, write and search files, risky tools opt-in.
Securely search and manage workspace context files for AI agents and teams.
User-owned files and explicit AI Memories for authorized assistants with scoped access.
Manage files and folders directly from your workspace. Read and write files, list directories, cre…