文件系统管理协议服务器

一个生产就绪的MCP（模型上下文协议）服务器，使AI代理能够完全控制文件系统——读取、写入、编辑、搜索、区分文件、执行命令和管理进程。内置Go，具有OAuth授权和RBAC。

特性

• 🗂️ 12个强大的工具 用于文件系统操作、shell执行和代理实用程序
• 🔐 基于JWT+CEL的RBAC --使用glob模式和JWT声明表达式限制每条路径的操作
• ⚡ 代币设计高效 --部分文件读取、批量编辑、范围差异、使用上下文控制进行搜索
• 🔑 符合OAuth RFC 8414/RFC 9728标准 — .well-known/oauth-protected-resource 和 .well-known/oauth-authorization-server
• 🛡️ JWT验证 --通过JWKS+CEL表达式进行本地验证
• 🚀 双重运输 --stdio用于本地客户端，HTTP用于远程客户端（Claude Web、OpenAI等）

工具

文件系统

壳牌和工艺

系统和公用设施

基于角色的访问控制

RBAC控制允许在哪些文件系统路径上执行哪些操作。规则按顺序评估——第一场比赛获胜。

操作类别

system_info 和 scratch 请勿触碰文件系统，始终是被允许的。

配置

rbac:
  enabled: true
  default_policy: deny # deny | allow

  rules:
    - name: "admins"
      when:
        - 'payload.groups.exists(g, g == "admin")'
      paths: ["/**"]
      operations: [read, write, exec]

    - name: "developers"
      when:
        - 'payload.groups.exists(g, g == "developer")'
      paths: ["/home/*/projects/**", "/tmp/**"]
      operations: [read, write]

    - name: "viewers"
      when:
        - 'payload.scope.contains("read")'
      paths: ["/home/*/projects/**"]
      operations: [read]

    - name: "anonymous - no JWT"
      when: []
      paths: ["/tmp/sandbox/**"]
      operations: [read]

• when --根据JWT有效载荷计算CEL表达式。一切都必须是真实的（AND）。没有JWT的空或缺失匹配请求
• paths --球状图案。 /** 后缀递归匹配所有内容
• operations — read, write, exec
• default_policy — deny （默认安全）或 allow （开放，用于发展）

⚠️ 警告：授予 exec 赋予代理完整的shell访问权限。来自的任何文件系统限制 paths 可以通过shell命令绕过。仅授予 exec 信任的身份。

安装

来源

需要Go 1.24+。

git clone https://github.com/achetronic/filesystem-mcp.git
cd filesystem-mcp
make build

输出： bin/filesystem-mcp-{os}-{arch}

从发布二进制文件

从下载预构建的二进制文件 发布 页面。二进制文件可用于linux/{386、amd64、arm64}和darwin/{amd64，arm64}。

为什么没有Docker镜像？

此MCP服务器旨在 控制主机文件系统 --读取、写入、编辑文件和执行shell命令。在容器内运行它会破坏它的目的：代理只会看到容器的文件系统，而不是你的。将整个主机文件系统绑定挂载到容器中会引入比直接运行二进制文件更糟糕的复杂性和安全隐患。

如果您需要网络可访问的部署（HTTP传输），请将二进制文件作为systemd服务或在反向代理后面运行。Dockerfile和Helm chart保存在仓库中，用于容器化部署有意义的边缘情况（例如，具有特定卷装载的沙盒CI环境），但它们是 不是推荐的方式 运行这个。

跑步

在本地运行

make run

默认配置在上启动HTTP服务器 :8080。对于stdio模式，修改Makefile以使用 docs/config-stdio.yaml.

客户端配置

标准模式（克劳德桌面、光标、VSCode）

make build

// claude_desktop_config.json
{
  mcpServers: {
    filesystem: {
      command: "/path/to/bin/filesystem-mcp-linux-amd64",
      args: ["--config", "/path/to/docs/config-stdio.yaml"],
    },
  },
}

HTTP模式（远程客户端）

npm i mcp-remote && make run

// claude_desktop_config.json
{
  mcpServers: {
    "filesystem-remote": {
      command: "npx",
      args: [
        "mcp-remote",
        "http://localhost:8080/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization: Bearer ${JWT}",
      ],
      env: {
        JWT: "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
      },
    },
  },
}

配置

配置基于YAML，通过加载 --config 旗帜。支持环境变量扩展($VAR / ${VAR}).

请参阅示例配置：

• HTTP模式 --JWT、RBAC、OAuth端点的完整配置
• 标准模式 --本地使用的最小配置

文档

• MCP授权要求
• RFC 9728——OAuth保护的资源元数据
• MCP Go库
• mcp远程包
• CEL规范

贡献

欢迎所有捐款！

• 打开一个问题 报告错误或请求功能
• 提交拉取请求 促进改进

许可证

根据 Apache 2.0许可证.