Filesystem MCP
Let your AI assistant work with your files, safely.
Read, search, edit, and patch files in the folders you choose. Secret files stay hidden, and risky changes wait for your OK.
接入你的智能体
发布者自己的命令。不是 PlugMCP 端点。
用我们的密钥与日志托管一份副本。
npx -y @j0hanz/[email protected]Claude Code 没有针对本地命令的安装链接。复制下方命令并在终端中运行。
claude mcp add j0hanz-filesystem-mcp -- npx -y @j0hanz/filesystem-mcp@2.21.0在终端中运行。
{ "mcpServers": { "j0hanz-filesystem-mcp": { "command": "npx", "args": [ "-y", "@j0hanz/[email protected]" ] } }}claude_desktop_config.json
远程 URL 还是本机命令? 两种安装方式的区别
来自发布者
Let your AI assistant work with your files, safely.
Read, search, edit, and patch files in the folders you choose. Secret files stay hidden, and risky changes wait for your OK.
Filesystem MCP server for AI assistants. Search, read, edit, and manage local files in directories you choose.
Model Context Protocol (MCP) is how AI apps such as Claude, GitHub Copilot in VS Code, and Cursor connect to tools. Filesystem MCP is an MCP server: a small program that runs on your computer and gives the AI 14 tools for working with files. You choose which folders it can use, and everything outside them is off limits.
Once it is connected, you can ask things like:
getUser to fetchUser in all .ts files. Show me the diff first."config.dev.json and config.prod.json?"server.log and explain the error."archive/2025/.".env files, private keys, and cloud credentials are blocked. The server
asks you before the AI deletes a non-empty folder, opens a folder you did
not allow, or writes over a file with create or move. Only create and
copies can skip that question, by passing overwrite: true. Edits made with
edit, patch, and replace_text apply without asking, but the AI can
show you the diff first with dryRun. If the AI should never change
anything, --read-only removes every tool that writes.grep, with a regex engine (RE2) that cannot hang, and by default the
server skips .gitignored files and folders like node_modules. Edits are
exact-match replacements that return an error when the text does not match,
and you can preview them as a diff first.How this server differs from the official
@modelcontextprotocol/server-filesystem,
checked against its README on 2026-10-11:
[!NOTE] You need Node.js 24 or later. Check with
node --version.
/path/to/project with the folder the AI may use. You can list
several folders.[!TIP] VS Code currently shares the folders you have open with the server, so the one-click VS Code install works without a path. In other apps, or over HTTP, put the folder in
args. If the AI says it has no folders, that is the fix.
Click Install in VS Code above, or add this to .vscode/mcp.json:
{
"servers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
}
}
}
Or from a terminal:
code --add-mcp '{"name":"filesystem","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest","/path/to/project"]}'
Click Install in Cursor above, then add your folder to args. Or add this
to .cursor/mcp.json in your project, or ~/.cursor/mcp.json for all
projects:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
}
}
}
For a one-click install, download
filesystem-mcp.mcpb,
open it with Claude Desktop, and pick the folders to allow. Claude Desktop's
built-in Node.js runs it. The extension's settings also let you turn on
read-only mode and block more files.
To set it up by hand, add this to claude_desktop_config.json
(Settings → Developer → Edit Config):
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
}
}
}
claude mcp add filesystem -- npx -y @j0hanz/filesystem-mcp@latest /path/to/project
Or install the plugin, which points the server at your current project:
/plugin marketplace add j0hanz/j0hanz-marketplace
/plugin install filesystem-mcp@j0hanz-marketplace
Add this to .vs\mcp.json in your solution folder, or %USERPROFILE%\.mcp.json
for all solutions:
{
"servers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest", "C:/path/to/project"]
}
}
}
The filesystem-mcp plugin sets the server up for your current project:
The container can only see the folders you mount. This setup blocks writes
twice, with the :ro mount and with the --read-only flag.
{
"mcpServers": {
"filesystem": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v",
"/path/to/project:/workspace:ro",
"ghcr.io/j0hanz/filesystem-mcp:latest",
"--read-only",
"/workspace"
]
}
}
}
Drop :ro and --read-only to let the AI make changes. VS Code and Visual
Studio use "servers" instead of "mcpServers". See
Running in Docker for more.
Windsurf, Cline, and most other clients use the same mcpServers JSON as
Claude Desktop above. In any client, the server is:
npx-y, @j0hanz/filesystem-mcp@latest, then one or more foldersYou can also install it globally and run filesystem-mcp /path/to/project:
npm install -g @j0hanz/filesystem-mcp
✎ changes files. --read-only removes these tools.
Search and listing tools skip hidden files, .gitignored files, and folders
like node_modules, dist, and .git unless the AI asks for them.
Most people only need the folder argument. These options cover the common cases:
Flags go in args after the package name, for example
["-y", "@j0hanz/filesystem-mcp@latest", "--read-only", "/path/to/project"].
The full configuration reference covers every flag and environment variable, the complete secret-file list, limits, HTTP setup with API keys, Docker, and troubleshooting.
If you find a vulnerability, please report it privately. SECURITY.md explains how.
You can also call Filesystem MCP from your own code: an agent, an editor plugin, a web app, a CI job, or a script. The same rules apply as for an AI app, so your code cannot reach outside the allowed folders or read secret files.
import { Client } from '@modelcontextprotocol/client';
import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
const dir = '/path/to/project';
const client = new Client(
{ name: 'my-app', version: '1.0.0' },
{ capabilities: { elicitation: { form: {} } }, versionNegotiation: { mode: 'auto' } },
);
client.setRequestHandler('elicitation/create', async () => ({ action: 'decline' }));
await client.connect(
new StdioClientTransport({
command: 'npx',
args: ['-y', '@j0hanz/filesystem-mcp', dir],
cwd: dir,
}),
);
const result = await client.callTool({ name: 'search_text', arguments: { searchPattern: 'TODO' } });
const { matches } = (result.structuredContent ?? result._meta) as { matches: unknown[] };
console.log(matches);
await client.close(); // stops the server process; without it the script never exits
The basics:
_meta for tools that write their own text (list,
search_text, edit, ...) and in structuredContent for stat,
create, and list_roots. read is the exception: the file's text is
only in the text block, and _meta holds metadata about it.elicitation capability and
answer them in a handler, or, on the 2026-07-28 protocol, take them as data
(input_required) and answer later.filesystem-mcp://file/{+path}; internal://instructions and the
get-help prompt hold the server's guide for models.The client guide has the details, tested with the
TypeScript and Python SDKs, and examples/ has six runnable
clients:
Filesystem MCP runs entirely on your machine. This policy covers the npm
package, the Docker image, and the .mcpb desktop extension.
Bug reports, ideas, and pull requests are welcome. Start with CONTRIBUTING.md. It covers setup, running the server from source, and the checks a pull request needs.
If Filesystem MCP is useful to you, a star on GitHub helps other people find it.
Filesystem MCP server for AI assistants. Search, read, edit, and manage local files in directories you choose.
{ "mcpServers": { "j0hanz-filesystem-mcp": { "command": "npx", "args": [ "-y", "@j0hanz/[email protected]" ] } }}工具
暂无工具列表。远程服务器在首次健康检查后会获得工具列表。
常见问题
在本页复制适用于 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 配置。它使用发布者的安装方式,而不是 PlugMCP 代理。
此记录未列出必需的环境变量。
@j0hanz/filesystem 通过 stdio 在本地运行。
上次检查时间:2026-11-16。 Filesystem MCP server for AI assistants. Search, read, edit, and manage local files in directories you choose.