Local MCP Filesystem Server

本地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

设置

1. 克隆存储库：

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

1. 安装依赖项：

npm install

1. 创建沙盒目录：

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（免费套餐）

1. 安装ngrok并登录。

1. 配置您的ngrok authtoken一次：

ngrok config add-authtoken 

1. 以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

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

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

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

示例端点：

https://.ngrok-free.app/mcp/local-filesystem

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

1. 安装 cloudflared.

1. 以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

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

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

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

例子：

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

两个选项的注意事项：

• 公共URL可能会在会话之间更改。
• 保持 MCP_BEARER_TOKEN 每当暴露端点时启用。
• 客户端必须发送 Authorization: Bearer 如果启用了承载身份验证。
• 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的交互式工具，可帮助您自定义服务器配置，而无需手动编辑代码。

使用发电机

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

# Windows
start generator/index.html

# macOS
open generator/index.html

# Linux
xdg-open generator/index.html

1. 配置您的设置：

- 设置所需的基本目录 - 选择要启用/禁用的工具 - 自定义安全设置 - 设置服务器名称和版本

1. 生成您的自定义 server.js 文件

1. 生成器将根据您的需求创建一个即用型服务器配置

发电机的优点

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

安全

沙盒执法

所有操作仅限于配置 BASE_DIR:

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

HTTP安全控制

• 承载令牌认证：设置 MCP_BEARER_TOKEN 需要 Authorization: Bearer
• 速率限制：每个客户端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" }
  ]
}

配置

环境变量

服务器常量

编辑 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

链接

• 仓库:
• 问题:
• MCP协议:

积分

与 模型上下文协议SDK