Mcp Smb Server

MCP SMB Server

一个基于 Model Context Protocol（MCP），供 AI Agent 使用的运行时文件访问网关。

该项目允许 AI Agent 在运行时访问 SMB/CIFS 共享或本地文件系统路径，同时 保留原生文件系统权限强制机制。

如果底层系统无法读取某个文件，Agent 也无法读取。

---

本项目不是什么

• ❌ 不对文件系统进行索引
• ❌ 不使用嵌入或向量数据库
• ❌ 不进行数据同步或预复制
• ❌ 不绕过权限
• ❌ 不提供 IAM 或策略引擎

---

本项目能做什么

• ✅ 仅在访问时公开文件
• ✅ 依赖原生 SMB / OS 权限强制机制
• ✅ 使用 MCP 作为运行时控制平面
• ✅ 支持 SMB 和 本地文件系统后端
• ✅ 通过 stdio 通信（适用于 VS Code / Agent）

---

项目缘起

大多数 AI 文件集成采用以下模式：

Filesystem → Sync → Index → Embed → Agent

这会破坏权限模型，并使撤销权限成为不可能。

本项目采用以下方式：

Agent → MCP → Runtime filesystem access → Native permission check

不建立索引。不复制数据。不重新实现策略。

---

后端

本地模式

• 访问本地目录
• 限制在已配置的基础路径内
• 使用 OS 权限

SMB 模式

• 访问 SMB/CIFS 共享
• 由 SMB 服务处理授权
• 配置文件中不存储凭据

---

可用的 MCP 工具

list_directory

列出指定路径下的文件和目录。

参数

• path（字符串，必需）

---

read_file

读取文件的指定长度部分。

参数

• path（字符串，必需）
• max_bytes（数字，可选，默认值：8192）

---

配置

配置属于进程级配置，在启动时加载一次。

有关详细配置示例，请参阅配置指南。

快速开始：

# SMB mode with environment variables
export MCP_MODE=smb
export SMB_ADDR=localhost:445
export SMB_SHARE=finance
export SMB_AUTH=ntlm
export SMB_USER=alice
export SMB_PASSWORD=your_password
./mcp-smb-server

# Local mode with config file
./mcp-smb-server --config config.yaml

---

架构

MCP → FileBackend → { Local | SMB }

服务不会做出授权决策。
所有访问决策均由底层文件系统或 SMB 服务作出。

---

本项目有意不包含的功能

• 集中式策略管理
• 审批工作流
• 跨后端访问规则
• 审计汇总

本项目定义了一个精简且正确的执行边界，可在此基础上构建更高层级的治理能力。

---

安装

前置条件

• Go 1.24 或更高版本
• SMB 模式：可访问 SMB/CIFS 服务
• 本地模式：具备相应的文件系统权限

构建

git clone <repository-url>
cd mcp-smb-server
go build -o mcp-smb-server ./cmd/server

---

许可证

Apache License 2.0