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., "@universal-fs-mcp search src for TODO and show file names and line numbers"
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.
一个通用、宿主无关的 MCP 文件系统服务器。
基于官方 TypeScript SDK（@modelcontextprotocol/sdk）+ zod，走 stdio 传输，不依赖任何特定沙盒或客户端，任何能跑 Node.js 18+ 的环境都能用。
下载 universal-fs-mcp.mcpb（或到 Releases 页面），双击安装即可，无需 node 环境配置、无需 npm install。
安装过程中会让你选择一个工作区目录，之后所有文件操作都被限制在该目录内。
.mcpb是 MCP Bundle 格式（官方打包规范），需要宿主应用支持，例如 Claude for macOS / Windows。若你的客户端不支持.mcpb，请走下面的「从源码运行」。
Related MCP server: MCP Filesystem Server
git clone https://github.com/jingchenGOD/universal-fs-mcp.git
cd universal-fs-mcp
npm install
npm run build注意：仓库里不含
dist/（已在.gitignore中忽略）。 从源码运行必须先跑npm install && npm run build，否则没有dist/index.js，MCP 客户端无法启动服务器。 用上面的.mcpb一键安装的话，不需要做任何构建。
沙箱化：所有路径 path.resolve 后校验必须落在工作区根目录内，../ 穿越会被直接拒绝
省 token：fs_grep 只回文件名 + 匹配次数 + 行号，不吐整行内容；fs_read 支持按行切片
安全写入：fs_write 默认不覆盖已有文件；fs_edit 在匹配到多处时拒绝执行，除非显式允许
零污染：stdout 只走 MCP 协议，所有日志输出到 stderr
依赖极简：仅 @modelcontextprotocol/sdk、zod 和 Node 内置模块
仓库里的 manifest.json 是 MCP Bundle 的打包配置（规范版本 0.3）：
字段 | 值 |
|
|
|
|
|
|
|
|
| 类型 |
改完代码后重新打包：
npm run build
npm install -g @anthropic-ai/mcpb # 首次需要
mcpb validate manifest.json
mcpb pack . universal-fs-mcp.mcpb打包工具在 npm 上的包名是
@anthropic-ai/mcpb（不是@modelcontextprotocol/mcpb，后者不存在）。.mcpbignore会把src、tsconfig.json和typescript等打包期依赖排除，包体约 2.5 MB。
环境变量 | 默认值 | 说明 |
|
| 工作区根目录。所有路径参数都相对它解析，且不允许越出该目录。强烈建议显式设置。 |
手动启动（供调试）：
MCP_WORKSPACE_ROOT=/workspace node dist/index.js工具 | 参数 | 作用 |
|
| 列出目录内容；目录带 |
|
| 按行读取文本文件，返回指定行区间。第一条是 |
|
| 查询路径是否存在，返回类型（file/directory）、大小、修改时间；不存在时返回明确提示而非报错 |
|
| 写入文件，父目录不存在会自动递归创建；文件已存在且 |
|
| 精确字符串替换。匹配为 0 处时报错；匹配到多处且未设 |
|
| 正则检索文本文件。只返回文件名、匹配次数和行号数组，绝不返回匹配行内容；自动跳过 |
所有路径参数都支持相对路径（相对 MCP_WORKSPACE_ROOT）或该目录内的绝对路径。
以 DeepSeek Harness 为例，在 profile 的 cordis.patch.yml 中追加：
- insert:
- id: mcp-universal-fs
name: "@deepseek-ai/dsh-mcp-client"
config:
serverName: universal-fs
transport: stdio
command: node
args:
- /绝对路径/universal-fs-mcp/dist/index.js
cwd: /你的工作区
env:
MCP_WORKSPACE_ROOT: /你的工作区
toolCallTimeoutMs: 60000
failOnStartupError: false注册后工具名形如 mcp__universal-fs__fs_list。
其他客户端（Claude Desktop、Cursor 等）通用写法：
{
"mcpServers": {
"universal-fs": {
"command": "node",
"args": ["/绝对路径/universal-fs-mcp/dist/index.js"],
"env": { "MCP_WORKSPACE_ROOT": "/你的工作区" }
}
}
}所有路径在 path.resolve 之后用 path.relative 校验，越出根目录一律抛错
写操作是普通 writeFileSync，没有回滚机制，重要文件请先用 fs_read 读取备份
服务器以 stdin 上的 MCP 协议通信，不要用交互式终端直接运行后手敲命令
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| new_text | Yes | ||
| old_text | Yes | ||
| replace_all | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | . | |
| keyword | Yes | ||
| max_files | No | ||
| ignore_case | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | . | |
| show_hidden | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| end_line | No | ||
| start_line | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| content | Yes | ||
| overwrite | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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?
Tool has no description.
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.
v1.0.0fs_editfs_grepfs_listfs_readfs_statfs_writeScored across 6 tools
The verbs (list, read, stat, write, edit, grep) map to mostly distinct filesystem operations, and the fs_ prefix makes the target domain obvious. The main risk is fs_write vs fs_edit (overwrite/create vs in-place modification) and fs_read vs fs_stat, ambiguities that no descriptions exist to resolve.
Every tool follows the exact same pattern: fs_ prefix plus a short lowercase verb, all snake_case. There are no deviations or mixed conventions.
Six tools is well-scoped for a filesystem server, covering the core read/inspect/search/write operations without padding. Each tool appears to earn its place.
The surface covers reading, listing, stat, writing, editing, and searching, but there is no delete/remove, move/rename, copy, or explicit mkdir operation. These are standard filesystem lifecycle operations whose absence will force agents to find workarounds or fail.
Securely search and manage workspace context files for AI agents and teams.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Manage files and folders directly from your workspace. Read and write files, list directories, cre…
A real-time, multiplayer filesystem for agents and humans: shared files, live edits, history.