在 NAS 使用场景里一个很常见的需求是让 AI 智能体读取 SMB 共享中的文件。飞牛 fnOS 这类基于 Linux 的 NAS 系统自带存储管理和 SMB 文件共享能力但要把 SMB 共享信息开放给 Claude、Dify、Cline 这类 MCP 客户端中间还需要一个连接层也就是 MCP Bridge。MCP Bridge 的作用是把智能体发出的工具调用请求翻译成 SMB 操作再把 SMB 返回的文件列表、文件内容翻译回结构化数据。下面按“部署篇”的完整链路来拆解SMB 共享怎么建、MCP Bridge 怎么在 fnOS 上跑起来、智能体怎么连上去以及连接失败时该检查哪一段。这篇文章适合已经有一台飞牛 fnOS 或类似 NAS、想用智能体读取 NAS 文件信息的开发者阅读。文章会从概念讲起然后给出 Docker Compose 部署示例、MCP 客户端配置示例以及一份可以直接对着用的排查清单。完成阅读后你能够自己复现一条“智能体 - MCP Bridge - SMB 共享 - 文件信息返回”的最小链路。1. 先理解这条链路的组成SMB、MCP 与 Bridge 各自的职责1.1 SMB 解决的是文件共享MCP 解决的是工具调用标准化SMBServer Message Block是网络文件共享协议Windows、macOS、Linux 都内置支持。飞牛 fnOS 上开启 SMB 服务后局域网里的电脑或手机可以通过smb://192.168.1.10/share这种方式访问 NAS 上的文件夹。SMB 解决的是“文件如何在网络上被共享、读写、删除”这层问题它和 NFS、FTP 属于同一类事物。MCPModel Context Protocol是模型上下文协议。简单说它让 AI 应用通过标准方式连接外部工具和数据源。一个 MCP Server 可以暴露工具、资源和提示词MCP Client 比如 Claude Desktop、Cline、Dify会负责发现工具、展示参数、执行调用。你不需要在智能体的提示词里手写一份 “SMB API 文档”只要把 MCP Server 配置好智能体就能知道有哪些工具可用以及每个工具需要传入什么参数。两者的分工可以这样理解SMB 负责把文件共享出去MCP 负责把“读取文件的操作”标准化成智能体可以调用的工具。如果只想让人手动访问 NASSMB 就够了如果想让智能体自动看到文件信息就必须在 SMB 之上加一层 MCP 封装。1.2 APEX MCP BRIDGE 在链路里承担什么角色APEX MCP BRIDGE 在这里可以理解为 MCP 协议和 SMB 协议之间的翻译层。它本身通常是一个运行在 Docker 容器里的服务内部使用 SMB 客户端工具连接 NAS对外则以 MCP 协议暴露工具。常见暴露的工具包括列出共享目录列出目录下的文件读取文件内容创建目录或上传文件删除或重命名文件当智能体想“查看 SMB 共享目录里有哪些文件”时MCP Bridge 会接收一个工具调用请求例如调用list_files参数是路径/它再用 SMB 协议连接 NAS执行目录列举最后把结果返回给智能体。对智能体来说它只知道自己调用了一个工具对 NAS 来说它只知道有一个 SMB 客户端访问了共享文件。这里要强调一点MCP Bridge 不是文件代理服务器。它不会把整个 SMB 共享缓存到本地每次工具调用都可能发起一次 SMB 连接。因此SMB 认证速度、局域网连通性和共享目录大小都会直接影响智能体的响应速度。1.3 一次最小调用的数据流从智能体问题到文件列表返回可以用一个最小示例理解整条链路用户提问“SMB 共享目录下有哪些 PDF 文件”数据流如下智能体判断需要读取文件信息。MCP Client 根据工具描述调用list_files传入路径/。请求通过 HTTP 或 SSE 发送给 MCP Bridge。MCP Bridge 使用配置好的 SMB 账号连接飞牛 fnOS 的 445 端口。SMB 服务读取共享目录返回文件和文件夹列表。MCP Bridge 把结果转换成 JSON 返回给 MCP Client。智能体基于返回结果生成“目录下有 docs 文件夹和 report.pdf 文件”这样的回答。整个过程的难点不在任何一步单独执行而在于七步之间的协议转换和网络连通。后面的部署和排查基本都围绕这条链路展开。注意不要只验证“服务跑起来了”还要验证“工具被注册了”和“工具调用能返回数据”。服务启动只是第一步。2. 部署前先把 fnOS 的存储、SMB 共享和账号准备好2.1 环境清单fnOS、Docker、SMB 共享与 MCP 客户端部署前建议先确认环境。不同版本的 fnOS 界面文字会有差异但涉及的能力是固定的环境项要求说明飞牛 fnOS能正常访问管理界面基于 Debian 的 NAS 系统自带存储管理Docker 能力已启用用于运行 MCP Bridge 容器SMB 服务已启用且局域网可访问需要开放 445 端口共享文件夹至少一个测试共享例如smb-docsSMB 账号一个专用账号建议不要使用管理员账号MCP 客户端Claude Desktop、Cline、Dify 任一用于验证工具注册和调用如果原始环境里没有现成的共享文件夹先创建测试目录如果 SMB 服务没有启用下面的所有配置都不会生效。2.2 在 fnOS 上创建共享文件夹并启用 SMB 服务在飞牛 fnOS 上建议按照下面的顺序操作登录 fnOS 管理界面。进入存储管理器找到“共享文件夹”或类似入口。创建一个共享文件夹例如smb-docs。在系统设置中启用 SMB 服务。给smb-docs配置 SMB 访问权限。记录 fnOS 的局域网 IP例如192.168.1.10。创建共享文件夹的目的是明确“智能体只能看到哪些目录”避免把整个存储空间暴露给 MCP Bridge。这一步在最初可能被忽略但一旦以后要收紧权限重新规划目录的成本会很高。启用 SMB 时最好确认一下 SMB 服务监听的协议版本。大部分现代 NAS 会默认启用 SMB2 和 SMB3Windows 10/11、macOS 以及 Linux 客户端都能正常访问。如果局域网里还有老系统需要访问 SMB要单独评估协议兼容性而不是把 SMB1 重新打开。2.3 创建专用 SMB 账号并设置目录权限建议创建专用账号例如mcp-bridge。这个账号只用于 MCP Bridge 连接 NAS不对应日常管理账号。权限设置上遵循最小权限原则只给mcp-bridge分配smb-docs目录的读写权限。如果只需要读取文件甚至可以只给只读权限。测试阶段可以先给读写方便验证上传类工具生产环境再收窄。创建账号后先记录一下账号名和密码。测试阶段密码可以简单一些后续再改成复杂密码并轮换。2.4 用 smbclient 或系统资源管理器验证共享可访问在部署 Bridge 之前先用其他设备验证 SMB 共享可访问。这一步非常关键如果 SMB 本身不通后续所有报错都会被误判成 MCP Bridge 的问题。Windows 用户可以在资源管理器地址栏输入\\192.168.1.10\smb-docsmacOS 用户可以在 Finder 中按Command K输入smb://192.168.1.10/smb-docsLinux 用户可以在另一台机器上安装smbclient后用命令行验证smbclient -L //192.168.1.10 -U mcp-bridge如果列出了共享名说明 SMB 服务和账号是通的。如果出现NT_STATUS_LOGON_FAILURE说明账号密码有问题如果出现NT_STATUS_CONNECTION_REFUSED说明 SMB 服务没有监听或网络端口不通。推荐先用内网 IP 验证不要在一开始就使用主机名。因为容器里如果解析不到 NAS 主机名会额外引入 DNS 问题。2.5 部署形态MCP Bridge 建议跑在 fnOS Docker 里MCP Bridge 的部署形态通常是在 fnOS 的 Docker 环境中跑一个容器。原因是 MCP Bridge 大多依赖自定义环境变量、端口监听和日志输出放在容器里更可控也方便清理。这时有一个容易踩的坑如果 Bridge 容器使用 Docker 默认的 bridge 网络那么容器内访问宿主机时不能使用127.0.0.1而应该使用 fnOS 的局域网 IP。只有在容器使用 host 网络时127.0.0.1才指向宿主机本身。注意容器内访问 SMB 服务要写 fnOS 的局域网 IP不要想当然写127.0.0.1。3. 为什么选 MCP Bridge三条技术路径的对比3.1 三条路径对比宿主目录、自写 HTTP 服务、MCP Bridge想让智能体看到 SMB 文件信息并不是只有 MCP Bridge 一种做法。把常见方案放在一起看才能理解为什么最后要选 Bridge。方案实现方式优点缺点方案 A直接挂载目录把 NAS 目录挂载到运行智能体的机器实现简单文件系统原生可见只能在能挂载 SMB 的机器上用跨机器、跨客户端场景难处理方案 B自写 HTTP 服务自己封装 REST API内部调用 SMB 命令可控性强能做业务逻辑客户端不通用每个工具都要管理认证、参数校验、错误处理方案 CMCP Bridge用标准 MCP 协议暴露 SMB 工具客户端原生支持工具声明和调用标准化多一个服务要部署需要理解 MCP 配置如果只是本机玩一下方案 A 确实最省事。但是当智能体跑在另一台服务器或者你想在多个 MCP 客户端里复用同一套文件操作能力时方案 C 的优势就比较明显。3.2 Bridge 在复用性和协议标准化上的优势选择 MCP Bridge核心原因是 MCP 协议正在成为智能体连接外部工具的通用接口。同一个 Bridge可以同时被 Claude Desktop、Cline、Dify 等客户端发现和调用。这意味着工具定义一次多个客户端复用。工具参数有 JSON Schema智能体能够自动生成正确参数。不需要在系统提示词里写“如何调用文件服务”的文档。后续增加新工具只需要在 Bridge 内部实现并重新暴露客户端自动发现。自写 HTTP 服务也能达到类似效果但缺点是每个客户端接入方式都不同。MCP Bridge 最大的价值就是标准化。3.3 学习环境与生产环境在方案上的差异学习环境里可以容忍密码简单、不加密、权限宽、日志全量输出。目标是快速跑通链路。生产环境则完全不同环境SMB 账号密码管理网络暴露日志学习环境直接用测试账号写进.env即可仅内网验证全量输出方便排查生产环境最小权限专用账号密钥管理工具定期轮换限制来源 IP脱敏、保留、告警如果一开始就在生产环境使用管理员账号和弱密码风险会很大。建议先在学习环境跑通最小链路再按生产要求加固。4. 在 fnOS 上用 Docker 部署 SMB TO MCP Bridge4.1 目录规划应用目录、配置文件和日志目录分开在 fnOS 的 Docker 数据目录下创建项目目录/data/mcp-bridge/ ├── docker-compose.yml ├── .env └── logs/目录分离的好处是容器升级或重建时配置文件和日志不会丢失。docker-compose.yml负责描述服务.env负责保存环境变量logs/用来挂载容器日志。不建议把密码直接写在docker-compose.yml里。这样如果有一天有人把 compose 文件分享出来或提交到代码仓库密码就会泄露。4.2 编写 docker-compose.yml容器化部署的骨架下面是一个用于说明部署思路的 Compose 示例。实际部署时镜像名、端口和变量名要以你确认过的项目文档为准services: smb-mcp-bridge: image: your-registry/smb-mcp-server:latest container_name: smb-mcp-bridge restart: unless-stopped env_file: - .env environment: TRANSPORT: http LISTEN_ADDR: 0.0.0.0 LISTEN_PORT: 8010 ports: - 8010:8010 volumes: - ./logs:/app/logs这里解释几个关键点restart: unless-stopped让容器在 NAS 重启后自动恢复。env_file从外部文件读取环境变量避免把密码写进 compose 主文件。LISTEN_ADDR: 0.0.0.0表示容器内监听所有网络接口这样外部客户端可以通过局域网 IP 访问。ports把容器的 8010 端口映射到宿主机供 MCP 客户端访问。如果你的 fnOS 界面没有提供 Docker Compose 能力也可以使用docker run方式部署下面是一个等价示例docker run -d \ --name smb-mcp-bridge \ --env-file .env \ -p 8010:8010 \ -v ./logs:/app/logs \ your-registry/smb-mcp-server:latest这里要说明命令中的your-registry/smb-mcp-server:latest只是示例。MCP Bridge 相关的镜像有很多社区实现安装前要确认镜像是否维护、是否支持 HTTP 传输方式、以及环境变量的命名是否一致。4.3 用 .env 管理 SMB 连接参数避免密码散落在配置里创建一个.env文件写入 SMB 连接参数SMB_HOST192.168.1.10 SMB_PORT445 SMB_USERNAMEmcp-bridge SMB_PASSWORDyour-password SMB_SHAREsmb-docs SMB_DOMAIN各参数含义如下SMB_HOSTfnOS 的局域网 IP。不要写成localhost。SMB_PORTSMB 服务默认端口是 445。SMB_USERNAME用于连接 SMB 的专用账号。SMB_PASSWORD账号密码。SMB_SHARE要暴露给 MCP 工具的共享名称。SMB_DOMAIN在没有域环境的家庭场景通常留空企业域环境按需填写。如果密码包含$、、空格等特殊字符不同容器对.env的解析规则不一致建议先测试。也可以在.env中对该值加引号但要注意有些镜像会把引号当成密码内容的一部分。最稳妥的办法是先把密码设成简单值验证链路再改复杂密码。4.4 启动容器并确认日志没有报错执行以下命令启动cd /data/mcp-bridge docker compose pull docker compose up -d启动后查看容器状态和日志docker ps | grep smb-mcp-bridge docker logs -f smb-mcp-bridge预期日志应该出现类似“listening on 0.0.0.0:8010”或“SMB connection ok”的信息。不同的 MCP Server 实现日志格式不同但至少应该能看出服务进程启动成功。MCP 传输层开始监听端口。如果有连接测试逻辑SMB 连接成功。如果日志里直接出现NT_STATUS_LOGON_FAILURE不要继续配置客户端先回第 2 章检查 SMB 账号和共享路径。如果容器退出查看退出原因常见的是端口被占用或环境变量缺失。4.5 关键参数速查SMB_HOST、SMB_SHARE 与传输方式参数含义常见值错误配置的表现SMB_HOSTfnOS 的局域网 IP192.168.1.10连接超时、拒绝连接SMB_PORTSMB 服务端口445报端口不可达SMB_USERNAME专用 SMB 账号mcp-bridge登录失败SMB_PASSWORD账号密码不推荐明文写死登录失败SMB_SHARESMB 共享名smb-docs返回共享不存在TRANSPORTMCP 传输方式http / sse客户端无法发现工具LISTEN_PORTMCP 服务监听端口8010客户端连接被拒这里最容易被忽略的是SMB_SHARE和SMB_HOST。SMB_SHARE填的是共享名称不是smb://...路径也不是挂载点。写错一个字符Bridge 启动可能没问题但工具调用会一直返回目录不存在。注意MCP 客户端的访问地址是 Bridge 的地址不是 NAS 的 SMB 地址。两者的端口、协议完全不同。5. 把 Bridge 接入 Claude Desktop、Cline、Dify 等智能体客户端5.1 MCP 客户端配置的共性URL、传输方式和认证无论使用哪个客户端MCP 配置本质上都是回答几个问题MCP Server 叫什么名字。通过什么传输方式访问。服务地址是什么。是否需要认证信息。对于部署在 NAS 容器里的 MCP Bridge通常填写http://192.168.1.10:8010/mcp这样的地址。192.168.1.10是 fnOS 的局域网 IP8010是映射出来的端口/mcp是 MCP 端点。具体端点路径以服务文档为准。一个常见的排查点是客户端跑在哪台机器就要从哪台机器访问 Bridge 地址。如果客户端和 NAS 不在同一网段还要先检查路由和防火墙。5.2 Claude Desktop 与 Cline以 mcpServers 方式接入Claude Desktop 或 Cline 这类客户端通常支持在配置文件中添加 MCP Server。配置思路如下{ mcpServers: { smb-bridge: { url: http://192.168.1.10:8010/mcp } } }这里的url要能由客户端所在机器访问。如果客户端和 NAS 在同一台机器上可以用localhost但更推荐直接写局域网 IP方便以后迁移客户端。Cline 这类编辑器插件一般有 MCP 管理界面。你可以在界面中选择“MCP Server”类型填入名称和 URL客户端会自动请求工具列表。配置完成后工具列表里应该出现list_directories、list_files等工具。5.3 Dify 添加本地 MCP 服务HTTP 类型工具注册Dify 的 Agent 或工作流里可以在“工具”区域添加“本地 MCP 服务”。选择 HTTP 类型后填入 Bridge 的访问地址Dify 会先拉取工具清单再让你选择哪些工具进入 Agent。Dify 侧要注意两点Dify 服务器必须能够访问 NAS 的 8010 端口不能填 Dify 容器内部地址。工具注册后如果 Dify 版本或 MCP 协议版本不匹配可能拉不到工具列表需要从协议兼容角度排查。实际应用时建议先只注册“列目录”和“读取文件”两个只读工具减少智能体误操作写文件的风险。5.4 工具注册成功后的预期效果与一次真实查询工具注册成功后MCP Client 的工具列表页会出现类似下面的工具list_directorieslist_filesread_file当用户输入“看看 SMB 共享目录下有哪些文件”时智能体会调用list_files传入路径/。Bridge 通过 SMB 读取共享目录后返回类似下面的 JSON[ { name: docs, type: directory }, { name: report.pdf, type: file, size: 204800, mtime: 2025-01-10T08:30:00Z } ]智能体再基于这个结果生成自然语言回答。到这里一条完整的 MCP 链路就通了。如果工具列表没有出现优先检查第 5.1 节的三个要素URL 是否可以从客户端访问、传输方式是否与 Bridge 一致、有没有认证头没有填。6. 按链路验证与排查从 SMB 连通到工具调用6.1 分段验证链路每一段都有独立的检查命令链路越复杂越要分段验证。推荐按下面顺序逐层检查第一步验证 SMB 本身。smbclient -L //192.168.1.10 -U mcp-bridge第二步验证 Bridge 容器状态。docker ps | grep smb-mcp-bridge docker logs --tail 50 smb-mcp-bridge第三步验证端口和网络。从客户端所在机器执行curl http://192.168.1.10:8010/mcp很多 MCP 服务对GET /mcp不一定有响应可以用curl -v观察是连接被拒还是返回响应。重点是确认网络通而不是纠结响应内容。第四步在客户端内查看工具列表。这一步需要进入 MCP 客户端界面查看工具是否注册成功。第五步实际调用一次只读工具例如list_files确认返回数据格式。每一段通过后再进入下一段能显著降低排查难度。6.2 常见问题排查表现象、原因、检查方式、解决方案问题现象常见原因检查方式处理建议容器启动后立即退出端口被占用或环境变量缺失docker logs看启动错误检查端口占用、补齐环境变量日志报 SMB NT_STATUS_LOGON_FAILURE账号密码错误用 smbclient 验证同一账号修正.env重启容器日志报共享不存在SMB_SHARE 填写错误用smbclient -L查看真实共享名改为正确的共享名称客户端连接不上 Bridge网络不通或端口未映射用curl从客户端访问端口检查防火墙、端口映射、IP 地址工具列表为空传输方式不匹配对比客户端配置与 Bridge 文档统一为 HTTP 或 SSE能列目录但读文件超时文件过大或网络不稳定复制一个小文件测试检查网络质量确认超时配置中文文件名乱码编码不一致查看 Bridge 日志返回内容设置 UTF-8 环境变量并重启NAS 没有读写权限SMB 目录权限不足在 NAS 上检查共享权限和账号权限给专用账号配置最小但足够的权限6.3 几个反复出现的坑容器 IP、特殊字符、协议版本与路径风格第一个坑在容器里访问宿主 NAS 时写了127.0.0.1。Docker bridge 网络下127.0.0.1表示容器自身而不是宿主机。要把SMB_HOST写成 fnOS 的局域网 IP或者改用 host 网络。第二个坑SMB 密码含特殊字符。.env文件对#、$等字符的处理可能和 shell 不同。建议先用无特殊字符的密码跑通再用安全方式处理复杂密码。第三个坑老系统访问 SMB 时的协议兼容问题。Windows 7 默认只能访问 SMB1而现代 NAS 往往默认关闭 SMB1。如果严格要求“老系统也能访问”不要在客户端重新打开 SMB1因为风险很高更好的方式是升级客户端或调整 NAS 允许的协议版本。第四个坑路径风格不一致。在 SMB 客户端里路径可能写\\192.168.1.10\smb-docs\folder但 MCP 工具参数往往传/folder或空路径。要仔细看 MCP 工具的参数说明确认路径是“共享内相对路径”还是“完整路径”。6.4 可复用的排错顺序从 SMB 到 MCP 逐层向后遇到任何问题都按照下面的优先级排查输入检查账号、密码、共享名、路径是否写对。文件路径和命名共享名和目录是否存在。容器配置环境变量是否加载、镜像版本是否正确。网络客户端能否访问 Bridge 端口、Bridge 能否访问宿主机 445 端口。协议客户端与 Bridge 的 MCP 传输方式是否一致。日志容器日志和 MCP 客户端的日志是否出现明确异常。版本限制MCP 客户端版本与 Bridge 使用的 MCP 协议版本是否兼容。这个顺序把“底层可访问性”放在前面避免在协议和配置上反复兜圈子。7. 生产化前要补上的权限、安全与发布清单7.1 使用最小权限账号严格限定可访问目录无论 MCP Bridge 怎么封装它最终都是用 SMB 账号去访问 NAS。如果这个账号对 NAS 所有共享都有读写权限智能体就有能力读取甚至修改整个 NAS 上的文件。建议为 Bridge 创建专用账号归属独立用户组。在共享文件夹权限中只给 Bridge 需要的目录授权。如果应用场景只是读取文件只开只读权限。定期检查该账号最近访问了哪些文件。MCP 让智能体具备操作文件的能力权限边界必须明确这是生产化最重要的前提。7.2 敏感信息、日志和镜像版本要纳入管理不要把账号密码写进代码仓库。.env文件要加入.gitignore。生产环境可以使用 Docker Secrets 或密钥管理工具注入环境变量密码要定期轮换。日志方面MCP Bridge 的日志可能会记录路径、文件名、返回内容。建议在日志中脱敏账号信息并且对日志设置保留周期。镜像版本要固定不要长期使用latest否则镜像更新可能带来不兼容变更。7.3 控制网络暴露面不建议公网映射MCP Bridge 监听0.0.0.0是为了让局域网内的多个客户端都能访问但这不等于要把服务直接暴露到公网。不建议在路由器上同时把 NAS 的 445 端口和 Bridge 的 8010 端口做公网映射。如果确实需要外网访问应该走成熟的安全方案而不是直接在公网裸奔。在局域网内部也可以按需做访问控制通过防火墙限制只有特定客户端 IP 能访问 8010。把 Bridge 容器放在独立的 Docker 网络里。不为不需要写操作的场景开放上传类工具。安全的原则是暴露越少风险越低。7.4 发布前检查清单与生产化扩展方向下面是一份可以直接对着用的发布前检查清单SMB 共享名、路径、账号、权限已经确认。使用专用账号不是管理员账号。SMB 445 端口从 Bridge 容器能访问。镜像版本固定不是latest。.env没有入库密码没有写在 compose 文件里。Bridge 容器启动了日志中没有 SMB 认证错误。MCP 客户端能够发现工具列表。使用只读工具完成了一次真实调用。客户端所在机器能访问 Bridge 端口。没有把 445 和 8010 端口直接映射到公网。日志保留策略和告警已配置。扩展方向上后续可以做三件事一是增加文件类型过滤让 MCP 工具只暴露文档、日志、图片等指定格式二是增加操作审计记录每一次工具调用来自哪个客户端、操作了什么路径三是把 SMB 只读账号收窄到只读权限再把 Bridge 接入 Agent 编排流程让智能体在指定目录中自动整理会议记录、分析日志或生成报表。部署一个 SMB TO MCP Bridge本质不是把镜像跑起来而是让链路里的每一段都明确SMB 共享可访问、Bridge 能连接、客户端能发现工具、工具调用能返回结果。先把最小链路验证通过再从只读扩展到写操作最后逐步加固账号权限和网络安全这套方案就能稳定地进入日常使用。