使用说明

本地MCP文件系统服务器

一种安全的模型上下文协议（MCP）服务器，为AI助手和其他MCP客户端提供沙盒文件系统访问。此服务器将所有文件操作限制在指定的基目录中，以确保安全和受控的文件系统交互。

特性

沙盒访问：所有文件操作都严格包含在配置的基目录中
安全第一设计：具有规范化和解析路径的路径遍历保护
读/写操作：全面的文件和目录操作
多个传输：支持通过stdio、HTTP或两者同时进行的MCP
交互式生成器：基于Web的工具，便于服务器配置和定制
符合MCP标准：适用于任何兼容MCP的客户端

可用工具

read_file -读取文件内容（支持UTF-8和base64编码）
write_file -使用可选的覆盖保护将内容写入文件
list_directory -列出带有类型信息的目录内容
stat_file -获取文件或目录的元数据
search_files -按名称递归搜索文件
make_directory -递归创建目录
delete_file -安全删除文件（拒绝删除目录）
rename_file -重命名或移动沙盒中的文件

安装

先决条件

Node.js（v16或更高版本）
npm

设置

克隆存储库：

git clone https://github.com/JimGile/local-mcp-filesystem-server.git
cd local-mcp-filesystem-server

安装依赖项：

npm install

mkdir -p C:/mcp-sandbox/base
# Or on Unix-like systems:
# mkdir -p /path/to/your/sandbox

用法

运行服务器

集 BASE_DIR 并选择一种运输方式 MCP_TRANSPORT.

默认传输方式为 both 当 MCP_TRANSPORT 未设置。

标准

Windows（PowerShell）：

$env:BASE_DIR="C:/mcp-sandbox/base"
$env:MCP_TRANSPORT="stdio"
node server.js

Windows（命令提示符）：

set BASE_DIR=C:/mcp-sandbox/base
set MCP_TRANSPORT=stdio
node server.js

Unix/Linux/macOS：

BASE_DIR="/path/to/your/sandbox" MCP_TRANSPORT="stdio" node server.js

HTTP传输

BASE_DIR="/path/to/your/sandbox" MCP_TRANSPORT="http" HTTP_HOST="127.0.0.1" HTTP_PORT="3000" HTTP_PATH="/mcp/local-filesystem" node server.js

启用承载令牌的HTTP：

BASE_DIR="/path/to/your/sandbox" MCP_TRANSPORT="http" HTTP_HOST="127.0.0.1" HTTP_PORT="3000" HTTP_PATH="/mcp/local-filesystem" MCP_BEARER_TOKEN="replace-with-strong-token" node server.js

默认HTTP端点：

http://127.0.0.1:3000/mcp/local-filesystem

同时进行两次传输（默认）

BASE_DIR="/path/to/your/sandbox" MCP_TRANSPORT="both" HTTP_HOST="127.0.0.1" HTTP_PORT="3000" HTTP_PATH="/mcp/local-filesystem" node server.js

通过隧道（ngrok或Cloudflare）暴露HTTP端点

使用这些选项进行临时/临时外部访问。

选项A:ngrok（免费套餐）

安装ngrok并登录。
配置您的ngrok authtoken一次：

ngrok config add-authtoken <YOUR_NGROK_AUTHTOKEN>

以HTTP模式启动此MCP服务器（或 both)在本地主机上：

$env:BASE_DIR="C:/mcp-sandbox/base"
$env:MCP_TRANSPORT="http"
$env:HTTP_HOST="127.0.0.1"
$env:HTTP_PORT="3000"
$env:HTTP_PATH="/mcp/local-filesystem"
node server.js

在另一个终端中，启动ngrok隧道脚本：

.\Start-NgrokTunnel.ps1 -LocalHost "127.0.0.1" -LocalPort 3000 -HttpPath "/mcp/local-filesystem"

复制打印件 MCP endpoint 将URL导入您的MCP客户端。

示例端点：

https://<random-subdomain>.ngrok-free.app/mcp/local-filesystem

选项B：Cloudflare隧道（快速隧道）

安装 cloudflared.
以HTTP模式启动此MCP服务器（或 both)在本地主机上：

$env:BASE_DIR="C:/mcp-sandbox/base"
$env:MCP_TRANSPORT="http"
$env:HTTP_HOST="127.0.0.1"
$env:HTTP_PORT="3000"
$env:HTTP_PATH="/mcp/local-filesystem"
node server.js

在另一个终端中，运行一个快速的Cloudflare隧道：

cloudflared tunnel --url http://127.0.0.1:3000

从终端输出中复制生成的公共URL，并附加您的MCP路径。

例子：

Public URL from cloudflared: https://<random-subdomain>.trycloudflare.com
MCP endpoint to use:         https://<random-subdomain>.trycloudflare.com/mcp/local-filesystem

两个选项的注意事项：

公共URL可能会在会话之间更改。
保持 MCP_BEARER_TOKEN 每当暴露端点时启用。
客户端必须发送 Authorization: Bearer <token> 如果启用了承载身份验证。
MCP请求必须使用 POST 到已配置 HTTP_PATH.

与Claude Desktop或其他MCP客户端一起使用

将服务器添加到MCP客户端配置中。对于Claude Desktop，编辑您的 claude_desktop_config.json:

{
  "mcpServers": {
    "local-filesystem": {
      "command": "node",
      "args": ["C:/Data/Projects/local-mcp-filesystem-server/server.js"],
      "env": {
        "BASE_DIR": "C:/mcp-sandbox/base",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

交互式生成器

这 generator 该文件夹包含一个基于web的交互式工具，可帮助您自定义服务器配置，而无需手动编辑代码。

使用发电机

打开 generator/index.html 在您的网络浏览器中：

# Windows
start generator/index.html

# macOS
open generator/index.html

# Linux
xdg-open generator/index.html

配置您的设置：
- 设置所需的基本目录
- 选择要启用/禁用的工具
- 自定义安全设置
- 设置服务器名称和版本
生成您的自定义 server.js 文件
生成器将根据您的需求创建一个即用型服务器配置

发电机的优点

无需代码编辑：所有配置选项的可视化界面
验证：在生成之前，确保您的配置有效
快速定制：轻松启用/禁用特定的文件系统操作
文档：每个设置的应用内解释

安全

沙盒执法

所有操作仅限于配置 BASE_DIR:

路径规范化：在访问之前，所有路径都经过规范化和解析
父母横向保护：拒绝访问基目录外的尝试
Symlink检查：尽可能验证Symlink目标
真实路径分辨率：用途 fs.realpath() 解析实际的文件系统路径

HTTP安全控制

承载令牌认证：设置 MCP_BEARER_TOKEN 需要 Authorization: Bearer <token>
速率限制：每个客户端IP的可配置请求限制
请求日志记录：HTTP请求包括方法/路径/状态/持续时间/ip日志

安全模型

BASE_DIR = C:/mcp-sandbox/base

✅ Allowed:
  - C:/mcp-sandbox/base/file.txt
  - C:/mcp-sandbox/base/subfolder/doc.md

❌ Rejected:
  - C:/mcp-sandbox/base/../other/file.txt
  - C:/outside-folder/file.txt
  - Symlinks pointing outside BASE_DIR

例子

读取文件

请求：

{
  "tool": "read_file",
  "arguments": {
    "path": "config.json"
  }
}

答复：

{
  "ok": true,
  "path": "config.json",
  "content": "{ \"setting\": \"value\" }"
}

编写文件

请求：

{
  "tool": "write_file",
  "arguments": {
    "path": "data/output.txt",
    "content": "Hello, World!",
    "overwrite": true
  }
}

答复：

{
  "ok": true,
  "path": "data/output.txt",
  "bytesWritten": 13
}

列出目录

请求：

{
  "tool": "list_directory",
  "arguments": {
    "path": "."
  }
}

答复：

{
  "ok": true,
  "path": ".",
  "entries": [
    { "name": "config.json", "type": "file" },
    { "name": "data", "type": "directory" }
  ]
}

配置

环境变量

变量	描述	默认值	必填
`BASE_DIR`	沙盒操作的基本目录	`C:/mcp-sandbox/base`	是的
`MCP_TRANSPORT`	运输方式： `stdio`, `http`，或 `both`	`both`	没有
`HTTP_HOST`	启用HTTP时的HTTP绑定主机	`127.0.0.1`	没有
`HTTP_PORT`	启用HTTP时的HTTP端口	`3000`	没有
`HTTP_PATH`	MCP HTTP路由路径	`/mcp/local-filesystem`	没有
`MCP_BEARER_TOKEN`	HTTP请求所需的承载令牌（设置时）	空	没有
`HTTP_RATE_LIMIT_WINDOW_MS`	HTTP速率限制窗口（毫秒）	`60000`	没有
`HTTP_RATE_LIMIT_MAX_REQUESTS`	每个客户端每个窗口的最大HTTP请求数	`60`	没有
`HTTP_REQUEST_LOGGING`	启用HTTP请求日志记录(`true`/`false`)	`true`	没有

服务器常量

编辑 server.js 自定义：

const SERVER_NAME = "local-mcp-filesystem-server";
const SERVER_VERSION = "1.0.0";

发展

项目结构

local-mcp-filesystem-server/
├── server.js              # Main MCP server implementation
├── Start-LocalMcpFilesystemServer.ps1   # Local server launcher
├── Start-NgrokTunnel.ps1   # Temporary ngrok tunnel launcher
├── package.json           # Project dependencies and metadata
├── README.md              # This file
└── generator/             # Interactive generator tool
    ├── index.html         # Generator UI
    └── assets/            # Generator resources
        ├── script_*.js    # JavaScript modules
        └── style_*.css    # Stylesheets

在发展中奔跑

npm start

测试

使用手动工具调用测试服务器，或与Claude Desktop等MCP客户端集成。

验证生成的输出回归检查：

npm run validate:generated

故障排除

常见问题

错误：“基本目录不存在”

确保 BASE_DIR 路径存在且可访问
创建目录： mkdir -p /path/to/base

错误：“拒绝访问：路径解析到允许的基目录之外”

请求的路径试图逃离沙盒
检查 .. 外部的路径段或绝对路径 BASE_DIR

服务器未连接到MCP客户端

验证客户端配置指向正确 server.js 路径
检查Node.js是否在您的PATH中
确保已安装依赖项(npm install)

无法访问HTTP端点

确认 MCP_TRANSPORT 设置为 http 或 both
检查主机/端口/路径值： HTTP_HOST, HTTP_PORT, HTTP_PATH
验证没有防火墙或端口冲突阻止访问

贡献

欢迎投稿！请随时提交问题和拉取请求。

许可证

ISC

链接

仓库: https://github.com/JimGile/local-mcp-filesystem-server
问题: https://github.com/JimGile/local-mcp-filesystem-server/issues
MCP协议: https://modelcontextprotocol.io

积分

与模型上下文协议SDK