Files.com MCP Server

Files.com MCP サーバー

files-com-mcp Python パッケージを使用すると、AI アプリケーションから Files.com を操作できます。ローカルでの使用のみを想定しており、STDIO のみをサポートしています。MCP クライアントが、同じマシン上でパッケージをサブプロセスとして起動します。

ネットワーク経由の MCP 接続には、Files.com hosted MCP service を使用してください。

クライアントがサブプロセスに渡す環境で、FILES_COM_API_KEY を設定してください。ローカルパッケージは、サイトの操作を実行するため、Files.com API に送信リクエストを行います。

Files.com は、脆弱なレガシーサーバーを常時稼働のセキュアなファブリックに置き換える、クラウドネイティブな次世代 MFT、SFTP、セキュアなファイル共有プラットフォームです。あらゆるクラウド、プロトコル、パートナーをまたぐミッションクリティカルなファイルフローを自動化し、人によるコラボレーションを支援するとともに、手作業をなくします。

軍用グレードの暗号化で保護された汎用 SFTP、AS2、HTTPS、および 50 以上のネイティブコネクターにより、Files.com はガバナンス、可視性、コンプライアンスを単一の画面に集約します。

はじめに

Files.com Python MCP パッケージを使うと、Claude Desktop やその他のローカル MCP クライアントから、Files.com サイト上のファイルのアップロードとダウンロード、フォルダーの検索、ユーザーの管理、自動化の実行ができます。API キーの権限を使用し、その操作はほかの API クライアントと同様にログに記録されます。

Python パッケージは、STDIO（標準入出力）経由のローカル使用のみをサポートしています。MCP クライアントが同じマシン上でパッケージを起動し、ネットワークリスナーを介さずにそのプロセスと直接通信します。パッケージから Files.com API への送信アクセスは引き続き必要です。

MCP とは

Model Context Protocol（MCP）は、LLM が処理の一環として実際の API を呼び出すための標準インターフェースです。MCP サーバーはモデルにツール群を提供し、Files.com の各ツールはサイト上で認証された操作を行います。サーバーに接続すると、モデルは次のことができます。

• クラウドシステムとオンプレミスシステム間でファイルを転送する
• フォルダーやファイルのメタデータを検索する
• ユーザーを作成、管理する
• アーカイブや共有などのワークフローを自動化する

一般的なユースケース

運用チーム向けアシスタント。 社内チャットボットが、依頼に応じてファイルを取得またはアーカイブします。

自動化されたワークフロー。 エージェントがサポート依頼の受信に応じて、その案件に必要なファイルを取得またはアップロードします。

開発者向けコパイロット。 開発に特化した LLM が、デバッグ中にユーザーを作成したり、フォルダーをプロビジョニングしたり、ファイルを読み取ったりします。

ローカル MCP とホスト型 MCP

Claude Desktop など、STDIO サーバーを起動するクライアントでは、ローカル Python パッケージを使用してください。

ネットワーク経由で MCP に接続するクライアントには、Files.com hosted MCP service を使用してください。サーバーは Files.com が運用するため、Python パッケージをインストールする必要はありません。開発中も含め、Python パッケージを HTTP または SSE サービスとして実行することはサポートされていません。

uv をインストールし、LLM クライアントに 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 hosted MCP service を使用してください。

要件

お使いの MCP クライアントは、ローカルの STDIO サーバーを起動できる必要があります。お使いのマシンから Files.com API へのアウトバウンドアクセスが必要です。

例では uvx を使ってサーバーを実行します。uvx は uv に含まれています。Python ツールを独自の隔離環境で実行するため、uv 以外に手動でインストールや設定を行う必要はありません。まず uv をインストールしてください。サーバーを Docker で実行することもできます。

サーバーの登録

クライアントのローカル STDIO サーバーコマンドを uvx に設定し、引数として files-com-mcp を指定します。uvx は初回使用時にパッケージをダウンロードし、クライアントがサーバーを起動するたびに実行します。

Claude Desktop の設定では、これらの設定を JSON で示しています。他のクライアントでは、ローカル STDIO サーバーの追加方法について、各クライアントの説明に従ってください。

認証

サーバーは、クライアントから渡される環境変数 FILES_COM_API_KEY から API キーを読み取り、Files.com に対して認証します。モデルはそのキーのユーザーが実行できる操作をすべて実行できるため、この用途のキーを作成する際は、エージェントに必要な権限だけを付与してください。

ローカルファイル転送の制限

任意で、クライアントのサーバー環境に 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_API_KEY と並べて "FILES_COM_LOCAL_ROOT": "/home/user/Documents" を追加し、お使いのマシンにある既存の絶対ディレクトリを指定してください。変更後は Claude Desktop を再起動してください。詳しくはローカルファイル転送の制限を参照してください。

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

Docker での実行

files-mcp リポジトリには、MCP サーバーと Python 3.11、および必要なすべての依存関係をパッケージ化する Dockerfile が含まれているため、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 とグループ ID に置き換え、/Users/you を自分のホームフォルダーに置き換えてください。

• -i は、プロトコルで使用するコンテナの標準入力を開いたままにします。-t は追加しないでください。ターミナルを使うと出力ストリームが結合され、プロトコルが壊れます。
• --rm は、セッションの終了時にコンテナを削除します。--init は小さな init プロセスをコンテナの最初のプロセスとして実行します。このプロセスは停止シグナルをサーバーに転送し、子プロセスを回収します。
• --user は、サーバーを自分のユーザー ID とグループ ID で実行するため、作成したダウンロードフォルダーに書き込むことができ、ダウンロードしたファイルの所有者も自分になります。
• 値を指定しない -e FILES_COM_API_KEY は、クライアントが渡す環境変数からキーをコピーするため、キーがコマンドラインに表示されません。

サーバーはログを標準エラーに書き込みます。

アップロードとダウンロード

ホストフォルダーをマウントすると、その中のファイルをコンテナ内で利用できます。イメージでは FILES_COM_LOCAL_ROOT=/work が設定されており、ローカルでのアップロードとダウンロードは /work に制限されます。サーバーを起動する前に両方のホストフォルダーを作成し、ダウンロードフォルダーにコンテナのユーザーが書き込めるようにしてください。アップロードするファイルを含むフォルダーを読み取り専用で /work/uploads にマウントし、ダウンロードフォルダーを読み書き可能な状態で /work/downloads にマウントします。クライアントの設定には、ホスト上の絶対パスを使用してください。

Docker は、ダウンロードできない権限でホストフォルダーを作成することがあります。例のように、まず mkdir -p でフォルダーを作成し、コンテナのユーザーがダウンロードフォルダーに書き込めることを確認してください。

転送ツールに指定するのは、マシン上のパスではなくコンテナ内のパスです。モデルにファイルの転送を依頼するときは、/work/downloads/report.pdf のように、/work/uploads または /work/downloads 以下のコンテナパスを指定してください。ホスト上の絶対パスは、-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 リソースのカテゴリに分けて、以下のツールを公開します。各ツールはサイト上の1つの操作に対応し、サーバーが保持する API キーの権限で実行されます。

ツールセットを絞り込む

モデルは、短いリストからのほうが適切なツールを確実に選択できます。LLM が Files.com ツールを一貫性なく使用している場合、原因はほとんどの場合、選択肢が多すぎることです。多くのクライアントでは、MCP サーバーのツールを1つずつ有効化または無効化できます。エージェントのタスクに必要なツールだけを有効にしてください。

自動化

ツール	説明
Find_Automation	自動化を表示
List_Automation	自動化の一覧を表示

ファイルシステム

ツール	説明
Begin_Delete_File	ファイル／フォルダーを削除し、そのファイル操作を返します。削除が保留中または処理中の場合、この処理が返された後もバックグラウンドで続行されます。完了を確認するには、ファイル移行を確認してください。ファイル移行の完了を待っても、削除はキャンセルされません。
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	1 つ以上のパスから 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 キーを使用する場合、ユーザーが管理者であれば、API 全体にフルアクセスできます。ユーザーが管理者でない場合は、そのユーザーがアクセスできるファイルにのみアクセスでき、API のサイト管理機能へのアクセスは許可されません。

プレースホルダーの YOUR_API_KEY を実際の API キーに置き換えてください。

並べ替えとフィルタリング

Files.com の API リソースのいくつかには、リソースの複数のインスタンスを返すリスト操作があります。リスト操作では、並べ替えとフィルタリングができます。

並べ替え

返されるデータを並べ替えるには、sort_by メソッド引数を渡します。

各リソースで有効な並べ替えフィールドのセットは固有であり、一度に並べ替えられるフィールドは 1 つだけです。

フォルダー一覧エンドポイントに関する特記事項

歴史的な理由と、さまざまな他のクラウドベースの 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 の比較ヘルパーは、パスの区切り文字とドットセグメントを正規化してから、同梱のバージョン管理された比較マップを適用します。共有の例では、独自の照合を実装するインテグレーション向けに、正確な比較結果を示しています。このマップでは、16 進数の Unicode スカラー値をキーとして使用します。エントリーがない文字はそのまま保持され、置換文字列が空の場合は文字が削除され、その他の置換文字列には複数の文字が含まれる場合があります。各置換は一度だけ適用し、その結果を再度正規化したり小文字化したりしないでください。

比較結果は照合にのみ使用してください。API リクエストには元の表記のパスを送信し、表示やローカルのファイル名にも元の表記を保持してください。比較結果は、元のパスと表記や長さが異なる場合があります。

比較では末尾の空白も意味を持ちます。report.txt と report.txt は異なるファイルパスであり、SDK ヘルパーはスペース、タブ、改行を保持します。フォルダー名の末尾に空白を付けることはできません。パスのルール全体については、Unicode 正規化を参照してください。

ワークスペース

ワークスペースは、Files.com サイト内のファイル、ユーザー、グループ、パートナー、インテグレーション、ワークフローをまとめます。インテグレーションは、部門やプロジェクト向けにワークスペースをプロビジョニングし、サイト管理者にすることなく、その運用をチームに委任できます。すべてのサイトには ID が 0 のデフォルトワークスペースがあり、追加のワークスペースにはそれぞれ独自の ID とルートフォルダーがあります。

アカウントのメンバーシップ、リクエストコンテキスト、権限の付与は、それぞれ異なる役割を果たします。ワークスペース内にアカウントを作成すると、そのアカウントの所属先が決まります。ワークスペースを選択すると、リクエストが操作するリソースが決まります。権限の付与によって、呼び出し元がそのワークスペースで実行できる操作が決まります。ワークスペースを選択しても、そこへのアクセス権は付与されません。

アカウントと管理者アクセス

ユーザーまたはグループの workspace_id は、そのアカウントが所属するワークスペースを識別します。カスタムワークスペースに所属するアカウントは、そのワークスペース内にとどまります。デフォルトワークスペースのユーザーとグループには、ワークスペース 0 に既存のアカウントを保持したまま、1 つ以上のカスタムワークスペースで権限を付与できます。

アカウント	ワークスペース管理者の割り当て	範囲
カスタムワークスペースに所属するユーザー	ユーザーの workspace_admin を true に設定します。	そのユーザーが所属するカスタムワークスペース。
デフォルトワークスペースのユーザー	カスタムワークスペースのルートフォルダーで、そのユーザーに admin 権限を作成します。	ルートで権限が付与された各カスタムワークスペース。
デフォルトワークスペースのグループ	カスタムワークスペースのルートフォルダーで、そのグループに admin 権限を作成します。	各メンバーは、ルートで権限が付与された各ワークスペースの管理者権限を継承します。

workspace_admin は、ユーザーが実効的に持つ管理者アクセス権の要約ではありません。デフォルトワークスペースのユーザーは、直接またはグループを通じてルートで権限を付与されることで、workspace_admin が false のままカスタムワークスペースを管理できます。グループには workspace_admin フィールドはありません。アカウントのフィールドについては、ユーザーとグループをご覧ください。

カスタムワークスペースのルートで admin 権限を付与すると、そのファイル、ユーザー、グループ、パートナー、ワークフロー、インテグレーションに対する完全なワークスペース管理者権限が付与されます。サブフォルダーで admin 権限を付与すると、そのフォルダーとその配下に対するフォルダー管理者権限が付与されますが、ワークスペースの管理権限は付与されません。その他の権限レベルでは、ワークスペースの管理権限を伴わず、対応するフォルダーアクセス権が付与されます。各権限レベルについては、権限をご覧ください。

サイト管理者は、デフォルトワークスペースのアカウントに対するワークスペース間の割り当てを管理します。ワークスペース管理者は、自身の範囲内でアカウントと権限を管理します。サイト管理者はすべてのワークスペースへのアクセス権を保持します。ワークスペースの権限を追加しても、サイト管理者の権限範囲は狭まりません。管理者の運用上の範囲とサイト全体の管理機能については、製品ドキュメントをご覧ください。

リクエストコンテキストと API キー

リクエストで X-Files-Workspace-Id REST ヘッダーを指定すると、対象のワークスペースを選択できます。SDK のリクエストオプションと CLI の設定でも、同じ選択内容が送信されます。ワークスペースを選択すると、ワークスペーススコープのリソースはそのコンテキスト内で一覧表示、作成、変更され、通常のパスはそのルートを基準とします。

リソースのリクエストフィールド workspace_id は、そのリソースが所属するワークスペースを表します。これは、SDK のワークスペースリクエストオプションや REST ヘッダーとは別のものです。カスタムワークスペースでワークスペーススコープのリソースを作成する場合、workspace_id のデフォルト値には選択したワークスペースが設定されます。所属先が一致しない値は not-authorized/insufficient-permission-for-params で拒否されます。

API キーで別のワークスペースを選択するには、デフォルトワークスペースで作成されたフルアクセスキーが必要です。ユーザーキーでは、グループの権限を含め、そのユーザーの現在のアクセス権限が適用されます。デフォルトワークスペースで作成されたサイト全体のフルアクセスキーには、すべてのワークスペースでサイト管理者の権限があります。ファイル専用キーは、ユーザーが複数のワークスペースにアクセスできる場合でも、作成されたワークスペースにとどまります。カスタムワークスペースで作成されたキーは、そのワークスペース内にとどまります。これらの制限付きキーで別のコンテキストを選択すると、bad-request/invalid-workspace-id-header で拒否されます。

カスタムワークスペースに所属するアカウントは、通常の認証時にそのワークスペースのスコープになります。デフォルトワークスペースのユーザーの場合は、対話型ログインの設定に頼らず、連携用の対象ワークスペースを明示的に選択してください。認証情報については、API キーと認証をご覧ください。

隣のリクエストでは、アクセス権を付与した後、メンバー自身のデフォルトワークスペースのフルアクセスユーザーキーを使って、ワークスペース 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'

既存のグループへのワークスペースの委任

すでにデフォルトワークスペースのグループとして登録されている運用チームは、ルートの権限を 1 つ付与することで、カスタムワークスペースを管理できます。グループとそのメンバーはデフォルトワークスペースにとどまるため、同じチームに他のワークスペースで異なるアクセス権を付与できます。

まず、ワークスペース 0 でサイト管理者として、対象のワークスペース ID とグループ ID を取得します。以下の例では、ワークスペース 123、グループ 456、メンバーユーザー 789 を使用しています。実際の ID に置き換えてください。グループがワークスペース 0 に属し、対象のユーザーがそのメンバーであることを確認します。

デフォルトワークスペースのサイト全体のフルアクセスキー、またはサイト管理者に属するフルアクセスユーザーキーを使って、権限を作成します。リクエストコンテキストは 0 のままにし、修飾済みのルートパス _/Workspaces/123 を使用します。group_id にグループの ID を設定し、permission を admin、recursive を true に設定します。後で削除できるよう、返された権限の id を保存してください。デフォルトワークスペースの個人ユーザーに付与する場合は、group_id の代わりに user_id を使用します。

デフォルトワークスペースのグループの場合、サイト管理者はワークスペース 123 を選択し、空の path を使ってルートへのアクセスを付与することもできます。ワークスペース 0 の修飾済みパスは、デフォルトワークスペースのユーザーとグループのどちらにも使え、アカウントのスコープと対象ワークスペースを明示できます。パスにサブフォルダーを追加すると、ワークスペース管理者の権限ではなく、フォルダー管理者のアクセス権が付与されます。

権限を付与した後、メンバー自身の認証情報を使い、ワークスペース 123 を選択してリクエストを行います。たとえば、そのワークスペースのルートフォルダーを一覧表示します。メンバーはワークスペース内のファイルを操作し、ユーザー、パートナー、連携の管理など、ワークスペース管理者の操作を実行できます。サイト管理者のリクエストが成功しても、メンバーに意図したアクセス権があることの確認にはなりません。

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 を指定してメンバーの権限を一覧表示すると、グループメンバーシップを通じて継承された付与も含められます。ユーザーに直接付与された権限だけを一覧表示すると、Workspace 管理を提供する権限を見落とす可能性があります。Workspace 0 では、Custom Workspace のルートは _/Workspaces/123 として表示されます。Workspace 123 では、パスはそのルートを基準とします。ユーザーの有効な管理アクセスを示すものとして workspace_admin フィールドを扱うのではなく、ルートパスと permission=admin を確認してください。

権限リストに表示されるのは、管理アクセスの有効状態を示す単一のフラグではなく、個々の付与です。複数のグループに所属すると、それらのアクセス権が組み合わされます。group_id の代わりに group_ids を使用する権限では、指定されたすべてのグループに所属する必要があります。これは、同じ権限を複数の独立したグループに割り当てるための省略表記ではありません。

メンバーを削除すると、そのグループを通じて得ていたアクセス権は終了します。ルート権限を削除すると、すべてのメンバーに対するグループの Workspace 管理者権限が終了します。これらの変更によって、独立した直接付与や他のグループからの付与が解除されることはありません。そのため、アクセス権を取り消す際には、該当するすべての付与を確認してください。デフォルトの Workspace ユーザー API キーには、再作成しなくてもこれらの権限変更が反映されます。

SCIM を通じて管理されているグループメンバーシップにも、同じルールが適用されます。メンバーの追加を許可されたグループ管理者は、そのユーザーにグループがすでに持つ Workspace 管理者アクセスを付与できます。その権限を踏まえて、誰がグループを管理するかを決めてください。

Workspace 0 でサイト管理者として、返された id を指定して権限を削除します。削除の例では権限 ID 9001 を使用しています。作成リクエストで返された ID に置き換えてください。権限はその場で更新するのではなく、作成または削除します。より限定的なフォルダーアクセスが引き続き必要な場合は、明示的に割り当ててください。広範な権限を削除しても、それによって置き換えられた、より限定的な権限が復元されることはありません。

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 SDK やその他の直接連携を統合テスト環境で Files.com API に対してテストする際に便利な、Files.com API のモックサーバーを公開しています。このサーバーは認証情報を確認しません。YOUR_API_KEY などの任意のプレースホルダー API キーを送信し、実際の Files.com 認証情報は絶対に使用しないでください。

サーバーには 2 つのモードがあり、起動時に選択します。

• レガシーモード（デフォルト）では、必須パラメーターとパラメーターの型を確認した後、各 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 シリコン搭載 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 とダウンロード 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

開発

ツールの開発や変更を行う場合は、Python MCP パッケージを STDIO 経由でローカル実行してください。アップロードツールとダウンロードツールは、MCP が実行されているファイルシステムを使用します。ネットワーク接続には、Files.com のホスト型 MCP サービスを使用してください。

LLM ツールのテストには、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