Files.com MCP Server

Files.com MCP 服务

files-com-mcp Python 包可让你的 AI 应用与 Files.com 交互。它仅供本地使用，只支持 STDIO：你的 MCP 客户端会在同一台机器上将此包作为子进程启动。

如需通过网络连接 MCP，请使用 Files.com 托管 MCP 服务。

在客户端传递给子进程的环境中设置 FILES_COM_API_KEY。本地包会向 Files.com API 发出出站请求，以执行站点操作。

Files.com 是云原生的新一代 MFT、SFTP 和安全文件共享平台，可通过始终在线的安全架构取代脆弱的旧式服务器。自动化关键任务文件流，覆盖任意云、协议或合作伙伴，同时支持人员协作并消除手动操作。

Files.com 通过通用 SFTP、AS2、HTTPS 和 50 多种原生连接器，以及军用级加密，在统一界面中整合治理、可见性和合规性。

简介

Files.com Python MCP 包可让 Claude Desktop 和其他本地 MCP 客户端在你的 Files.com 站点上上传和下载文件、查询文件夹、管理用户并运行自动化流程。它使用你的 API 密钥权限，其操作日志记录方式与其他 API 客户端相同。

此 Python 包仅支持通过 STDIO（标准输入和输出）在本地使用。你的 MCP 客户端会在同一台机器上启动它，并直接与该进程通信，不会启动网络侦听器。此包仍需要能够出站访问 Files.com API。

什么是 MCP

模型上下文协议（MCP）是一种标准接口，大模型可通过它在工作过程中调用实际 API。MCP 服务会向模型提供一组工具，每个 Files.com 工具都是在你的站点上执行的一项经身份验证的操作。连接服务后，模型可以：

• 在云端和本地系统之间传输文件
• 查询文件夹和文件元数据
• 创建和管理用户
• 自动执行归档或共享等工作流

常见用例

运维团队助手。 内部聊天机器人会根据请求获取或归档文件。

自动化工作流。 Agent 会响应收到的支持请求，然后检索或上传该工单所需的文件。

开发者编程助手。 面向开发的大模型可在调试期间创建用户、配置文件夹或读取文件。

本地 MCP 与托管 MCP

对于可启动 STDIO 服务的客户端，请使用本地 Python 包，包括 Claude Desktop。

对于通过网络连接 MCP 的客户端，请使用 Files.com 托管 MCP 服务。服务由 Files.com 运行，因此你无需安装 Python 包。不支持将 Python 包作为 HTTP 或 SSE 服务运行，开发期间也不例外。

安装 uv，在你的大模型客户端中将 uvx files-com-mcp 注册为 MCP 服务，并通过 FILES_COM_API_KEY 环境变量为其提供 Files.com API 密钥。

https://pypi.org/project/files-com-mcp/

安装

files-com-mcp Python 包可让你的 MCP 客户端通过在本机运行的进程调用 Files.com API。它仅支持通过 STDIO（标准输入和输出）在本地使用。对于通过网络连接 MCP 的客户端，请使用 Files.com 托管 MCP 服务。

要求

你的 MCP 客户端必须能够启动本地 STDIO 服务。你的计算机需要能够出站访问 Files.com API。

示例使用 uvx 运行服务，它是 uv 的一部分。它会在独立的隔离环境中运行 Python 工具，因此除了 uv 本身之外，无需手动安装或配置任何内容。请先安装 uv。你也可以在 Docker 中运行服务。

注册服务

将客户端的本地 STDIO 服务命令设为 uvx，并将 files-com-mcp 设为参数。uvx 会在首次使用时下载软件包，并在每次客户端启动服务时运行它。

Claude Desktop 配置展示了这些设置的 JSON 格式。对于其他客户端，请按照相应说明添加本地 STDIO 服务。

身份验证

服务使用 API 密钥向 Files.com 进行身份验证。密钥从客户端传入的 FILES_COM_API_KEY 环境变量中读取。请使用专用密钥，并授予 Agent 所需的权限。用户密钥遵循其帐户权限，并受密钥权限范围、Workspace 以及文件操作路径限制的约束。API 密钥介绍了如何选择权限范围以及管理凭据的生命周期。

限制本地文件传输

你可以选择在客户端的服务环境中设置 FILES_COM_LOCAL_ROOT，并将其设为现有绝对目录路径，例如 /home/user/Documents。这会将上传和下载工具接受的客户端请求本地路径限制为该目录及其子目录。如果未设置此变量或变量值为空，传输可以使用服务可访问的任何本地路径。

服务在检查每个路径时会解析 .. 和符号链接，并拒绝解析到配置目录之外的路径。相对传输路径将相对于服务的工作目录解析。如果下载路径的父目录存在，下载可以在该目录中创建新文件。非空值必须指向现有绝对目录，否则服务将无法启动。

此设置不会隔离操作系统帐户；这由操作系统权限控制。仅授予运行服务的帐户对配置目录及其子目录的写入权限。另一个拥有该目录写入权限的帐户可以通过放置或更改符号链接，将传输重定向到目录之外，即使路径已经过检查也不例外。

此设置仅适用于本地传输路径。Files.com 路径仍遵循 API 密钥的权限。

uvx files-com-mcp

FILES_COM_API_KEY=your-api-key uvx files-com-mcp

FILES_COM_API_KEY=your-api-key FILES_COM_LOCAL_ROOT=/home/user/Documents uvx files-com-mcp

与 Claude 配合使用

Claude Desktop 使用 Files.com Python MCP 软件包从你的计算机调用 Files.com API。此配置仅支持通过 STDIO（标准输入和输出）在本地使用。如需通过网络连接到 MCP，请使用 Files.com 托管 MCP 服务。

Claude Desktop 从 claude_desktop_config.json 读取 MCP 服务。在 mcpServers 下方添加右侧的条目，将 FILES_COM_API_KEY 的值替换为 Files.com API 密钥，然后重启 Claude Desktop。MCP 快速入门介绍了各操作系统中文件的位置，并演示如何为另一个服务执行相同的步骤。

该条目通过 uvx 启动服务，因此必须先安装 uv；请参阅安装。

Claude 重启后，Files.com 工具会显示在其工具列表中。工具按类别列出这些工具，并说明为什么只启用任务所需的工具会更好。

如需限制本地上传和下载，可选择在 env 对象中将 "FILES_COM_LOCAL_ROOT": "/home/user/Documents" 添加到 FILES_COM_API_KEY 旁边，并使用计算机上已有的绝对目录。更改后请重启 Claude Desktop。详情请参阅限制本地文件传输。

{
  "mcpServers": {
    "Files.com": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "files-com-mcp"
      ],
      "env": {
        "FILES_COM_API_KEY": "your-api-key"
      }
    }
  }
}

在 Docker 中运行

files-mcp 仓库包含一个 Dockerfile，其中打包了 MCP 服务、Python 3.11 及其所需的所有依赖项，因此运行 MCP 客户端的计算机需要安装 Docker，但不需要安装 Python 或 uv。

该容器仍是本地 STDIO 服务。MCP 客户端使用 docker run 启动它，并通过标准输入和输出发送、接收协议消息。客户端关闭标准输入时，容器会停止。它不会监听端口，也不会启动 HTTP 服务。对于通过网络连接到 MCP 的客户端，请使用 Files.com 托管 MCP 服务。

构建镜像

构建一次镜像，并在需要更新版本时再次构建。默认情况下，Docker 会针对构建机器的本机架构构建镜像。在仓库地址后添加 #v 和发行版编号，即可构建指定发行版。

镜像包含你所构建仓库中的软件包，以及它所依赖的最新版本 files-com Python SDK。如需改为安装指定版本的 SDK，请添加 --build-arg FILES_COM_SDK_VERSION= 和版本号。

注册服务

将客户端的本地 STDIO 服务命令设为 docker，并使用示例中的参数；然后在服务环境中将 API 密钥设为 FILES_COM_API_KEY。将 501:20 替换为通过 id -u 和 id -g 获取的你自己的用户和组 ID，并将 /Users/you 替换为你的主目录。

• -i 会保持容器的标准输入打开，以供协议使用。不要添加 -t。终端会合并输出流并破坏协议。
• --rm 会在会话结束时移除容器。--init 会以容器的第一个进程身份运行一个小型 init 进程，该进程会将停止信号转发给服务，并回收子进程。
• --user 会使用你的用户和组 ID 运行服务，使其能够写入你创建的下载文件夹，并让你成为所下载文件的所有者。
• 不带值的 -e FILES_COM_API_KEY 会从客户端传入的环境中复制密钥，因此密钥不会出现在命令行中。

服务会将日志写入标准错误。

上传和下载

挂载主机文件夹，即可在容器内访问其中的文件。该镜像设置了 FILES_COM_LOCAL_ROOT=/work，将本地上传和下载限制在 /work。启动服务前，请先创建主机上的两个文件夹，并确保容器用户对下载文件夹具有写入权限。将包含上传文件的文件夹以只读方式挂载到 /work/uploads，并将下载文件夹以可写方式挂载到 /work/downloads。在客户端配置中使用它们的主机绝对路径。

Docker 可能会以阻止下载的权限创建缺失的主机文件夹。请先使用 mkdir -p 创建文件夹，如示例所示，并确保容器用户能够写入下载文件夹。

传输工具使用容器内的路径，而非计算机上的路径。让模型传输文件时，请提供 /work/uploads 或 /work/downloads 下的容器路径，例如 /work/downloads/report.pdf。主机绝对路径仅用于 -v 挂载参数。

docker build -t files-com-mcp https://github.com/Files-com/files-mcp.git

mkdir -p "$HOME/Files.com/uploads" "$HOME/Files.com/downloads"

{
  "mcpServers": {
    "Files.com": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        "--user", "501:20",
        "-e", "FILES_COM_API_KEY",
        "-v", "/Users/you/Files.com/uploads:/work/uploads:ro",
        "-v", "/Users/you/Files.com/downloads:/work/downloads",
        "files-com-mcp"
      ],
      "env": {
        "FILES_COM_API_KEY": "your-api-key"
      }
    }
  }
}

FILES_COM_API_KEY=your-api-key docker run -i --rm --init \
  --user "$(id -u):$(id -g)" \
  -e FILES_COM_API_KEY \
  -v "$HOME/Files.com/uploads:/work/uploads:ro" \
  -v "$HOME/Files.com/downloads:/work/downloads" \
  files-com-mcp

工具

Files.com MCP 服务提供以下工具，按类别分为文件、文件夹、共享、用户、日志、自动化和其他 Files.com 资源。每个工具都会在你的网站上执行一项操作，并使用该服务持有的 API 密钥权限。

精简工具集

模型从较短的列表中更容易可靠地选出正确的工具。如果 LLM 使用 Files.com 工具的方式不一致，最可能的原因是可选工具过多。大多数客户端都允许逐个启用或停用 MCP 服务的工具；只启用 Agent 任务所需的工具。

自动化

工具	描述
Find_Automation	显示自动化
List_Automation	列出自动化

文件系统

工具	描述
Begin_Delete_File	删除文件/文件夹并返回其 File Action。删除处于待处理或处理中状态时，会在此操作返回后继续于后台执行；请检查其 File Migration 以确认是否完成。等待 File Migration 不会取消删除。
Copy_File	复制文件/文件夹
Create_Folder	创建文件夹
Delete_File	删除文件/文件夹
Find_File	按路径查找文件/文件夹
Gpg_Decrypt_File	解密 GPG 加密的文件，并将其保存到目标路径。
Gpg_Encrypt_File	使用 GPG 加密文件，并将其保存到目标路径。
List_For_Folder	按路径列出文件夹
Move_File	移动文件/文件夹
Transform_File	转换文件，并将输出保存到目标路径。
Unzip_File	将 ZIP 文件解压到目标文件夹。
Zip_File	从一个或多个路径创建 ZIP 文件，并将其保存到目标路径。
Zip_List_Contents_File	列出 ZIP 文件的内容。

集成

工具	描述
Find_Remote_Server	显示远程服务
List_Remote_Server	列出远程服务

日志记录

工具	描述
List_Action_Log	列出操作日志
List_Api_Request_Log	列出 API 请求日志
List_Automation_Log	列出自动化日志
List_Email_Log	列出电子邮件日志
List_Exavault_Api_Request_Log	列出 Exavault API 请求日志
List_External_Event	列出外部事件
List_File_Migration_Log	列出文件迁移日志
List_For_File_History	列出特定文件的历史记录。
List_For_Folder_History	列出特定文件夹的历史记录。
List_For_User_History	列出特定用户的历史记录。
List_Ftp_Action_Log	列出 FTP 操作日志
List_History	列出站点完整的操作历史记录。
List_Inbound_S3_Log	列出入站 S3 日志
List_Logins_History	列出站点登录历史记录。
List_Outbound_Connection_Log	列出出站连接日志
List_Public_Hosting_Request_Log	列出公共托管请求日志
List_Scim_Log	列出 Scim 日志
List_Settings_Change	列出设置变更
List_Sftp_Action_Log	列出 SFTP 操作日志
List_Sync_Log	列出同步日志
List_Web_Dav_Action_Log	列出 WebDAV 操作日志

共享 / 共享链接

工具	描述
Create_Bundle	创建共享链接
Create_Bundle_Notification	创建共享链接通知
Create_Bundle_Recipient	创建共享链接收件人
Delete_Bundle	删除共享链接
Delete_Bundle_Notification	删除共享链接通知
Find_Bundle	显示共享链接
Find_Bundle_Notification	显示共享链接通知
List_Bundle	列出共享链接
List_Bundle_Download	列出共享链接下载记录
List_Bundle_Notification	列出共享链接通知
List_Bundle_Recipient	列出共享链接收件人
List_Bundle_Registration	列出共享链接注册记录
Update_Bundle	更新共享链接
Update_Bundle_Notification	更新共享链接通知

用户账户

工具	描述
Create_Group	创建群组
Create_Permission	创建权限
Create_User	创建用户
Delete_Group	删除群组
Delete_Permission	删除权限
Delete_User	删除用户
Find_Group	显示群组
Find_User	显示用户
List_Group	列出群组
List_Permission	列出权限
List_User	列出用户
Update_Group	更新群组
Update_User	更新用户

身份验证

Files.com MCP 使用 API 密钥进行身份验证。

使用 API 密钥进行身份验证

在大多数情况下，建议使用 API 密钥进行身份验证，本网站上的示例也使用此方法。

如需使用 API 密钥，请先通过网页界面或通过 API 或 SDK生成 API 密钥。

用户密钥遵循其账户权限，并受密钥的权限范围、工作区以及文件操作路径限制的约束。只有账户和密钥都允许时，才能执行管理操作。API Keys 介绍凭据范围和生命周期；Workspaces 介绍请求上下文和委派管理。

请记得将占位符 YOUR_API_KEY 替换为实际的 API 密钥。

排序和筛选

Files.com API 的多个资源提供列表操作，可返回该资源的多个实例。列表操作支持排序和筛选。

排序

如需对返回的数据进行排序，请传入 sort_by 方法参数。

每种资源支持一组独有的有效排序字段，且每次只能按一个字段排序。

关于列出文件夹端点的特别说明

出于历史原因，并为了与各种其他基于云的 MFT 和 EFSS 服务保持兼容，列出文件夹内容时，文件夹始终会显示在文件之前。无论你提供什么排序参数，此规则都适用。这些参数仍会在文件夹优先于文件的初始排序之后生效。

筛选

筛选条件会应用于底层查询，以确定返回哪些结果。筛选条件可以单独应用，也可以与其他筛选条件组合使用，结果数据可按单个字段排序。

每种资源都支持一组独有的有效筛选字段、筛选组合，以及筛选条件与排序字段的组合。

筛选类型

筛选项	类型	说明
filter	精确	查找字段值与传入值完全匹配的资源。（即 FIELD_VALUE = PASS_IN_VALUE）。
filter_prefix	模式	查找指定字段以所提供的值为前缀的资源。此项适用于字符串值。
filter_gt	范围	查找字段值大于传入值的资源。（即 FIELD_VALUE > PASS_IN_VALUE）。
filter_gteq	范围	查找字段值大于或等于传入值的资源。（即 FIELD_VALUE >= PASS_IN_VALUE）。
filter_lt	范围	查找字段值小于传入值的资源。（即 FIELD_VALUE < PASS_IN_VALUE）。
filter_lteq	范围	查找字段值小于或等于传入值的资源。（即 FIELD_VALUE <= PASS_IN_VALUE）。

路径

Files.com 在保留文件和文件夹路径拼写形式的同时，会依据统一的大小写与 Unicode 规则对路径进行比较。在本地匹配路径时，请使用 SDK 比较辅助函数。

大小写

Files.com 使用基于固定 Unicode 比较映射的路径匹配方式，且不区分大小写。

例如，以下路径具有相同的比较键：

路径变体	比较键
Documents/Reports/Q1.pdf	documents/reports/q1.pdf
documents/reports/q1.PDF	documents/reports/q1.pdf
DOCUMENTS/REPORTS/Q1.PDF	documents/reports/q1.pdf

此行为适用于：

• API 请求
• 文件夹和文件查找操作
• 自动化和工作流

另请参阅：大小写敏感性文档

斜杠

文件夹名和文件名之间使用 /，路径开头和结尾不加斜杠。SDK 规范化辅助函数会将反斜杠转换为 /、移除重复的分隔符，并舍弃完全匹配的 . 和 .. 组件。舍弃 .. 不会移除其前面的文件夹名。

输入	规范化路径
folder/subfolder/file.txt	folder/subfolder/file.txt
/folder/subfolder/file.txt	folder/subfolder/file.txt
folder/subfolder/file.txt/	folder/subfolder/file.txt
//folder//file.txt	folder/file.txt
folder/../file.txt	folder/file.txt

### Unicode 与路径比较

Files.com 使用服务器和 SDK 共享的固定映射来比较路径。大小写和许多重音差异会被视为等同：Résumé.txt 和 resume.txt 指向同一个文件，q 后接组合尖音符与 q 也是如此。该映射还会处理其他等同情况，例如平假名和片假名。仅转换为小写或应用标准 Unicode 规范化形式，无法复现这些规则。

SDK 比较辅助工具会规范化路径分隔符和点段，然后应用附带的带版本的比较映射。共享示例为自行实现匹配逻辑的集成提供确切的比较结果。该映射使用十六进制 Unicode 标量值作为键：缺少条目时保留原字符，替换内容为空时移除该字符，其他替换内容可能包含多个字符。每项替换只应用一次，不要再次规范化或转换结果的大小写。

比较结果仅用于匹配。在 API 请求中发送原始路径拼写，并在显示和本地文件名中保留原样；比较结果的拼写或长度可能有所不同。

比较时，尾随空白有意义。report.txt 和 report.txt 是不同的文件路径，SDK 辅助工具会保留空格、制表符和换行符。文件夹名称不能以空白结尾。完整路径规则请参阅 Unicode 规范化。

工作区

工作区用于在 Files.com 站点内组织文件、用户、群组、合作伙伴、集成和工作流。集成可以为某个部门或项目配置工作区，并将其操作委派给团队，而无需将该团队设为站点管理员。每个站点都有一个默认工作区，ID 为 0；其他工作区则拥有各自的 ID 和根文件夹。

帐户成员资格、请求上下文和权限授予各有不同用途。在某个工作区中创建帐户决定了该帐户所属的位置。选择工作区决定了请求针对哪些资源进行操作。权限授予决定调用者可以在该工作区执行哪些操作。选择工作区本身不会授予对该工作区的访问权限。

账户和管理权限

用户或组的 workspace_id 用于标识该账户所属的工作区。属于自定义工作区的账户会保留在该工作区中。默认工作区的用户和组可以在一个或多个自定义工作区中获得权限，同时保留其在工作区 0 中的现有账户。

账户	工作区管理员分配方式	范围
属于自定义工作区的用户	将该用户的 workspace_admin 设为 true。	该用户所属的自定义工作区。
默认工作区用户	在自定义工作区的根文件夹上为该用户创建 admin 权限。	每个授予根文件夹权限的自定义工作区。
默认工作区组	在自定义工作区的根文件夹上为该组创建 admin 权限。	每位成员都会继承对每个授予根文件夹权限的工作区的管理权限。

workspace_admin 并不汇总用户实际拥有的管理权限。默认工作区用户可以通过直接授予或组根文件夹权限管理自定义工作区，而其 workspace_admin 仍为 false。组没有 workspace_admin 字段。有关账户字段，请参阅用户和组。

对自定义工作区根文件夹授予 admin 权限，即可获得对其文件、用户、组、合作伙伴、工作流和集成的完整工作区管理员权限。对子文件夹授予 admin 权限，则可获得该文件夹及其所有后代文件夹的文件夹管理员权限，但不能管理整个工作区。其他权限级别提供相应的文件夹访问权限，但不包含工作区管理权限。权限中定义了各个级别。

站点管理员管理对默认工作区账户的跨工作区权限分配。工作区管理员管理其权限范围内的账户和权限。站点管理员仍可访问每个工作区；授予工作区权限不会缩小站点管理员的权限范围。产品文档介绍了管理员的操作范围和站点级控制。

请求上下文与 API 密钥

你可以在请求中包含 X-Files-Workspace-Id REST 标头，以选择一个 Workspace。SDK 请求选项和 CLI 配置会发送相同的选择信息。选定 Workspace 后，Workspace 范围内的资源会在该上下文中列出、创建和更改，普通路径则相对于其根目录。

资源的 workspace_id 请求字段描述该资源所属的 Workspace。它与 SDK 的 Workspace 请求选项或 REST 标头不同。在 Custom Workspace 中创建 Workspace 范围内的资源时，其 workspace_id 默认设为所选 Workspace；若成员归属值不匹配，则请求会被拒绝，并返回 not-authorized/insufficient-permission-for-params。

使用 API 密钥选择其他 Workspace，需要使用在 Default Workspace 中创建的 Full Access 密钥。用户密钥遵循该用户当前的访问权限，包括群组权限。在 Default Workspace 中创建的站点级 Full Access 密钥在每个 Workspace 中都具有 Site Administrator 权限。Files Only 密钥会留在其创建时所在的 Workspace，即使其用户拥有跨 Workspace 的访问权限也是如此。在 Custom Workspace 中创建的任何密钥都仅限于该 Workspace。使用这些受限密钥选择其他上下文时，请求会被拒绝，并返回 bad-request/invalid-workspace-id-header。

属于 Custom Workspace 的账号在正常验证身份时会限定在该 Workspace 中。对于 Default Workspace 用户，应为集成明确选择目标 Workspace，而不要依赖交互式登录偏好设置。API Keys 和 Authentication 介绍了凭据。

相邻的请求使用成员自己的 Default Workspace Full Access 用户密钥，在分配访问权限后列出 Workspace 123 的根目录。

curl 'https://YOUR_SUBDOMAIN.files.com/api/rest/v1/folders/' \
  -H 'X-FilesAPI-Key: YOUR_MEMBER_API_KEY' \
  -H 'X-Files-Workspace-Id: 123'

将 Workspace 委托给现有群组

已在 Default Workspace 中设有群组的运营团队，可以通过一项根目录 Permission 管理 Custom Workspace。该群组及其成员仍留在 Default Workspace 中，因此同一团队在其他 Workspace 中可以获得不同的访问权限。

首先，以 Workspace 0 中的 Site Administrator 身份获取目标 Workspace 和 Group 的 ID。示例使用 Workspace 123、群组 456 和成员用户 789；请替换为你自己的 ID。确认该群组属于 Workspace 0，且目标用户是其成员。

使用 Default Workspace 的站点级 Full Access 密钥，或属于 Site Administrator 的 Full Access 用户密钥创建 Permission。将请求上下文保持为 0，并使用限定根路径 _/Workspaces/123。将 group_id 设为群组的 ID，将 permission 设为 admin，并将 recursive 设为 true。保存返回的 Permission id，以便之后移除权限。对于单个 Default Workspace 用户，请使用 user_id 代替 group_id。

对于 Default Workspace 群组，Site Administrator 也可以选择 Workspace 123，并使用空的 path 授予其根目录访问权限。在 Workspace 0 中使用限定路径，既适用于 Default Workspace 用户，也适用于群组，并能明确指定账号范围和目标 Workspace。在路径后追加子文件夹，将授予 Folder Admin 访问权限，而非 Workspace Administrator 权限。

授予权限后，以该成员身份发出请求，使用其自己的凭据并选择 Workspace 123，例如列出该 Workspace 的根文件夹。该成员可以使用 Workspace 中的文件并执行 Workspace Administrator 操作，例如管理其中的用户、Partners 和集成。Site Administrator 的请求成功，并不能证明该成员已获得预期的访问权限。

curl 'https://YOUR_SUBDOMAIN.files.com/api/rest/v1/workspaces' \
  -H 'X-FilesAPI-Key: YOUR_SITE_ADMIN_API_KEY' \
  -H 'X-Files-Workspace-Id: 0'
curl 'https://YOUR_SUBDOMAIN.files.com/api/rest/v1/groups' \
  -H 'X-FilesAPI-Key: YOUR_SITE_ADMIN_API_KEY' \
  -H 'X-Files-Workspace-Id: 0'

curl 'https://YOUR_SUBDOMAIN.files.com/api/rest/v1/permissions' \
  -X POST \
  -H 'X-FilesAPI-Key: YOUR_SITE_ADMIN_API_KEY' \
  -H 'X-Files-Workspace-Id: 0' \
  -H 'Content-Type: application/json' \
  -d '{"path":"_/Workspaces/123","group_id":456,"permission":"admin","recursive":true}'

权限检查与移除

使用 user_id 和 include_groups=true 列出成员的权限，以包含通过群组成员身份继承的授权。如果只列出直接授予用户的权限，可能会遗漏提供工作区管理权限的 Permission。在 Workspace 0 中，自定义 Workspace 根路径显示为 _/Workspaces/123；在 Workspace 123 中，路径相对于该根路径。检查根路径和 permission=admin，而不要将用户的 workspace_admin 字段视为其实际拥有的管理权限。

权限列表显示的是各项授权，而不是一个表示实际管理权限的标志。加入多个群组会合并这些群组授予的访问权限。使用 group_ids 而非 group_id 的 Permission 要求用户加入所有指定群组；这并不是将同一项授权分配给多个互不相关群组的简写。

移除成员会终止其通过该群组获得的访问权限。删除根 Permission 会终止该群组对所有成员的 Workspace Administrator 授权。这些变更不会影响独立的直接授权和其他群组授权，因此撤销访问权限时请检查所有适用的授权。默认 Workspace 用户 API 密钥会随这些权限变更而生效，无需重新创建。

通过 SCIM 维护的群组成员身份遵循相同规则。获准添加成员的 Group Admin 可以让这些用户获得该群组现有的 Workspace Administrator 访问权限。选择群组管理者时，请考虑其所拥有的权限。

请以 Workspace 0 中的 Site Administrator 身份，通过返回的 id 删除 Permission。移除示例使用 Permission ID 9001；请将其替换为创建请求返回的 ID。Permission 只能创建或删除，不能原地更新。如果仍需要更有限的文件夹访问权限，请明确分配；删除宽泛授权不会恢复它此前取代的较窄授权。

curl 'https://YOUR_SUBDOMAIN.files.com/api/rest/v1/permissions?user_id=789&include_groups=true' \
  -H 'X-FilesAPI-Key: YOUR_SITE_ADMIN_API_KEY' \
  -H 'X-Files-Workspace-Id: 0'
curl 'https://YOUR_SUBDOMAIN.files.com/api/rest/v1/permissions/9001' \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_SITE_ADMIN_API_KEY' \
  -H 'X-Files-Workspace-Id: 0'

外语支持

Files.com MCP 即将更新，将通过一种配置 方法支持本地化响应。该功能推出后，可用于引导 API 为适用的响应内容选择首选语言。

目前，语言支持仅适用于部分面向用户的字段，例如通知消息 和错误描述。

如果指定的语言不受支持，或未提供该值，API 将默认使用英语。

错误

模拟服务器

Files.com 发布了一个模拟 Files.com API 服务器，可用于在集成测试环境中，针对 Files.com API 测试你对 Files.com SDK 和其他直接集成的使用情况。 该服务器不会检查凭据：请发送任意占位 API 密钥（例如 YOUR_API_KEY），且切勿使用 真实的 Files.com 凭据。

服务器有两种启动时选择的模式：

• 旧版模式（默认）会检查必需参数和参数类型，然后为每个 API 端点返回固定的 示例响应。该模式不维护状态，也不会深入检查 提交内容是否正确，因此适用于测试 SDK 或 API 客户端的基本网络操作和 JSON 编码。
• 模拟模式会在内存中保留记录、文件和文件夹，因此测试可以创建、列出、更新 和删除资源、上传文件并下载相同字节，还可以让指定请求故意失败、 停滞或断开连接。未模拟的请求会返回明确错误，而不是示例响应。

使用 Docker 快速开始

安装好 Docker 后，运行以下命令，从 Docker Hub 启动已发布的镜像。该镜像会以 传统模式运行，地址为 http://127.0.0.1:4041，只有你的机器可以访问：将集成的 Files.com API 基础 URL 指向该地址，并使用占位 API 密钥。按 Ctrl+C 停止；--rm 会移除容器。

已发布的镜像仅为 linux/amd64 构建，因此命令会指定该平台； 否则，在其他架构的机器（例如 Apple silicon Mac）上运行 Docker 时，会查找该标签不存在的镜像。 latest 标签会指向最近发布的服务器，而 --pull=always 会在每次运行时重新拉取镜像，因此该镜像不一定包含模拟模式。要运行 模拟模式，请按下文所示从源代码构建镜像。

docker run --platform linux/amd64 --rm --pull=always -p 127.0.0.1:4041:4041 filescom/files-mock-server:latest

## In another terminal, with a placeholder API key:
curl -H "X-FilesAPI-Key: YOUR_API_KEY" http://127.0.0.1:4041/api/rest/v1/users

在 Docker 中运行模拟模式

要运行与源代码 README 中描述完全一致的服务器（包括模拟模式），请从 GitHub 上的源代码检出版本构建镜像，并使用记录在测试结果中的镜像 ID 运行。 目前仅验证过源代码的 linux/amd64 构建，因此两个命令都会指定该平台。

除非另有说明，模拟模式仅监听环回地址，因此命令使用 -b tcp://0.0.0.0:4041 将其绑定到容器的网络接口，并且只在你机器的 环回地址上发布端口。FILES_MOCK_TRANSFER_ORIGIN 用于告知服务器测试所使用的地址，以便它返回的上传和下载 URL 指向已发布的端口。

模拟模式只在服务器进程中保留状态。其位于 /__files_mock/v1 下的控制端点会报告服务器何时就绪、使用你的测试夹具重置服务器、添加故障规则，并返回收到的请求日志。 如果操作超出限制，服务器会拒绝处理，而不会截断数据。源代码中的 README 对所有这些内容、模拟的操作以及如何配置限制都有说明。

## In a checkout of the source:
docker build --platform linux/amd64 -t files-mock-server:local .
image=$(docker image inspect --format '{{.Id}}' files-mock-server:local)
echo "$image"   # record this ID with your test results
docker run --platform linux/amd64 --rm -e FILES_MOCK_MODE=simulation \
  -e FILES_MOCK_TRANSFER_ORIGIN=http://127.0.0.1:40410 \
  -p 127.0.0.1:40410:4041 "$image" -b tcp://0.0.0.0:4041

## In another terminal:
curl http://127.0.0.1:40410/__files_mock/v1/ready

使用 Ruby 从源代码运行

使用 Ruby 和 Bundler 从源代码启动服务器。启动时只读取一次 FILES_MOCK_MODE： 未设置或设为 legacy 时会启动传统模式，设为 simulation 时会启动模拟模式， 任何其他值都会导致启动失败并报错。传统模式会在所有 IPv4 接口的 4041 端口上监听，模拟模式则会在 127.0.0.1:4041 上监听。

bundle install

## Legacy mode
bundle exec puma

## Simulation mode
FILES_MOCK_MODE=simulation bundle exec puma

开发

开发或修改工具时，可在本地通过 STDIO 运行 Python MCP 软件包。上传和下载工具依赖 MCP 所在环境的文件系统。对于网络连接，请使用 Files.com 托管的 MCP 服务。

要测试大模型工具，我们推荐一款名为 inspector 的常用命令行程序。它会在本地端口启动 WebUI，命令输出会提供 Inspector GUI 的链接。 例如：http://127.0.0.1:6274

开发 - STDIO

FILES_COM_API_KEY="dummyKey" npx @modelcontextprotocol/inspector uv run -m files_com_mcp

开发 Claude 配置

{
  "mcpServers": {
    "Files.com": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/folder-containing-files_com_mcp",
        "run",
        "-m",
        "files_com_mcp"
      ],
      "env": {
        "FILES_COM_API_KEY": "CHangeME"
      }
    }
  }
}

MCP 注册表元数据

mcp-name: com.files/python-mcp