An Mcp Server That Gives Any Mcp Client Read Access To An Smb/cifs File Share Servers

remote-file-server-mcp

只需几分钟，即可安全地让任何 AI 助手读取你的 SMB/CIFS 文件共享。

---

这是什么？

一个 MCP（模型上下文协议） 服务，可将 Claude Desktop（或任何 MCP 客户端）连接到你的 SMB/CIFS 网络共享——包括 Windows 文件服务、NAS 磁盘、Samba 共享，以及任何 SMB 共享。

让 Claude 读取报告、搜索电子表格或总结存储在网络上的文档——无需移动任何文件、在聊天中粘贴凭据，也无需授予写入权限。

flowchart LR
    A("🤖 Claude Desktop\nor any MCP client"):::client
    B("🔌 file-server-mcp\n<i>this server</i>"):::server
    C("🗄️ SMB File Server\nWindows · NAS · Samba"):::storage

    A -- "MCP / stdio" --> B
    B -- "SMB 445 · encrypted" --> C

    classDef client  fill:#7c3aed,color:#fff,stroke:none
    classDef server  fill:#2563eb,color:#fff,stroke:none
    classDef storage fill:#0f766e,color:#fff,stroke:none

---

功能一览

默认只读	服务不提供任何写入操作，确保你的文件安全
凭据保留在本地	通过环境变量传入，绝不会出现在工具调用或聊天记录中
SMB 加密与签名	默认启用数据包签名和加密；将 SMB_ENCRYPT=false 设为仅禁用加密
阻止路径遍历	在发起任何 SMB 调用之前拒绝 .. 路径段
敏感文件拒绝列表	.env、*.key、*.pem、id_rsa、密钥库等文件永远不会被列出或读取
审计日志	每次工具调用都会记录为 JSON 条目（操作、路径、结果和工具专属元数据），绝不记录文件内容
Office 与 PDF 解析	将 Excel、Word、PowerPoint 和 PDF 文件解析为可读文本——需要可选的 [docs] 附加依赖
子目录允许列表	将服务限制为模型实际需要访问的目录

---

工具

工具	参数	说明
list_files	path（可选）	列出文件和目录。路径为空时表示共享根目录。返回 JSON。
read_file	path	返回文本内容。超大文件将返回预览或硬错误。Office/PDF 文件会进行解析。
get_file_info	path	返回元数据（大小、类型、时间戳），而不读取文件。
search_files	pattern、path（可选）、max_depth（可选）	按 glob 模式搜索（例如 *.csv）。递归深度最多为 max_depth（默认值为 5，最大值为 10），最多返回 200 个匹配项。

所有路径均相对于共享根目录，例如 reports/2024/q1.xlsx。

---

快速开始

选项 A — pip 安装

pip install -e /path/to/remote-file-server

然后在 MCP 客户端配置中使用 "command": "file-server-mcp"。

选项 B — uv（无需安装）

uv run --directory /path/to/remote-file-server file-server-mcp

选项 C — 从源代码运行

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python server.py

选项 D — Docker

docker build -t file-server-mcp .

运行时用法请参阅 Dockerfile。

---

MCP 客户端配置

在客户端配置文件的 mcpServers 下添加一项。

uv（从源代码运行，无需预先安装）：

{
  "mcpServers": {
    "file-server": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/remote-file-server", "file-server-mcp"],
      "env": {
        "SMB_HOST": "192.168.1.100",
        "SMB_SHARE": "my_share",
        "SMB_USERNAME": "my_user",
        "SMB_PASSWORD": "my_password"
      }
    }
  }
}

pip/uv pip（控制台脚本入口点）：

{
  "mcpServers": {
    "file-server": {
      "command": "file-server-mcp",
      "env": {
        "SMB_HOST": "192.168.1.100",
        "SMB_SHARE": "my_share",
        "SMB_USERNAME": "my_user",
        "SMB_PASSWORD": "my_password",
        "SMB_PORT": "445",
        "ALLOWED_PATHS": "reports,finance",
        "AUDIT_LOG_PATH": "/var/log/file-server-mcp/audit.jsonl"
      }
    }
  }
}

**安全提示：**此配置文件包含凭据，请限制其权限（在 macOS/Linux 上运行 chmod 600）。

保存后重启 MCP 客户端。

连接到多个服务

{
  "mcpServers": {
    "file-server-prod": {
      "command": "file-server-mcp",
      "env": { "SMB_HOST": "10.0.0.10", "SMB_SHARE": "Production", "...": "..." }
    },
    "file-server-dev": {
      "command": "file-server-mcp",
      "env": { "SMB_HOST": "10.0.0.20", "SMB_SHARE": "Development", "...": "..." }
    }
  }
}

---

环境变量

变量	必需	默认值	描述
SMB_HOST	是	—	SMB 服务的 IP 地址或主机名
SMB_SHARE	是	—	服务上的共享名称
SMB_USERNAME	是	—	SMB 身份验证用户名
SMB_PASSWORD	是	—	SMB 身份验证密码
SMB_PORT	否	445	SMB 端口
SMB_ENCRYPT	否	true	设置为 false 可禁用 SMB 加密（不建议）
SMB_TIMEOUT	否	30	SMB 连接或操作超时前的秒数
MAX_FILE_SIZE_MB	否	10	read_file 可读取的最大文件大小（MB）
READ_PREVIEW_LINES	否	100	对于超大文件，返回的行数。设置为 0 则直接报错
ALLOWED_PATHS	否	—	以逗号分隔的子目录允许列表，例如 reports,finance/2024
AUDIT_LOG_PATH	否	stderr	JSON 审计日志的文件路径。未设置时回退到 stderr

---

安全性

• 所有连接都必须启用 SMB 数据包签名。
• 路径遍历会被阻止——在发起任何 SMB 调用前都会拒绝 .. 路径段。
• 敏感文件拒绝列表涵盖 .env、*.key、*.pem、*.bak、id_rsa、*.pfx、*.p12、*.token、.netrc、.htpasswd、密钥库文件等。用于生产环境时，请结合 ALLOWED_PATHS，将访问范围限制为模型所需的目录。
• 文件大小限制可防止读取超出上下文窗口容量的文件。
• 审计日志记录会以 JSON 格式记录每次工具调用（操作、路径、结果、工具专属元数据），但绝不记录文件内容。
• 错误消息已做脱敏处理——不会向客户端暴露内部主机名、UNC 路径或凭据。

---

要求

• Python 3.11+
• 可访问 SMB 服务的网络连接（默认端口为 445）
• 对共享具有读取权限的 SMB 凭据