Apple Files

Apple Files MCP

macOS 上でファイル、Finder 関連、iCloud Drive のワークフローに対応するローカル MCP サーバーです。

機能

• 許可されたファイルのルートを一覧表示します
• ディレクトリの内容を確認します
• 名前でファイルやフォルダーを検索します
• UTF-8 テキストファイルを読み取ります
• ファイルのメタデータを確認します
• 最近使ったファイルを一覧表示します
• パスをデフォルトのアプリで開きます
• Finder でパスを表示します
• Finder タグを読み書きします
• 最近使った場所を一覧表示します
• ローカルの iCloud Drive の利用可否を報告します
• フォルダーを作成します
• パスを移動または名前変更します
• ファイルや空のフォルダーを削除します
• リソース：files://allowed-roots、files://recent、files://recent-locations、files://icloud-status
• プロンプト：files_prepare_attachment、files_organize_workspace
• コンテキストに制約のあるクライアント向けのツール検出ヘルパー search_tools と get_tool_info

この Mac にインストールする

uvx apple-files-mcp

git clone https://github.com/JonathanRReed/Apple-MCPs.git
cd Apple-MCPs
uv sync --all-packages

AI エージェントにインストールする

{
  "mcpServers": {
    "apple-files": {
      "command": "uvx",
      "args": ["apple-files-mcp"],
      "env": {
        "APPLE_FILES_MCP_ALLOWED_ROOTS": "/Users/you/Desktop,/Users/you/Documents,/Users/you/Downloads,/Users/you/Library/Mobile Documents/com~apple~CloudDocs",
        "APPLE_FILES_MCP_SAFETY_MODE": "safe_manage"
      }
    }
  }
}

クローンから実行する場合は、空の args とともに /path/to/Apple-MCPs/AppleFiles-MCP/start.sh をコマンドとして使用します。

Claude Code：

claude mcp add --transport stdio --scope user apple-files -- uvx apple-files-mcp

--scope user を指定すると、すべてのプロジェクトでサーバーを利用できます。代わりに、リポジトリの .mcp.json を通じて 1 つのリポジトリで共有するには、--scope project を使用します。

トランスポート

stdio がデフォルトで推奨されるトランスポートです。代わりに Streamable HTTP で提供するには、APPLE_FILES_MCP_TRANSPORT=streamable-http を設定します（APPLE_FILES_MCP_HOST と APPLE_FILES_MCP_PORT は任意です）。

プロンプトに関する注意事項

• tools/list は Files ツールの全機能を返します。コンテキストに制約のあるクライアントは、まず search_tools を使用し、次に必要な Files ツールの get_tool_info を使用できます。
• ユーザーがローカルファイルや添付ファイルに言及した場合は、Mail、Messages、Notes、Shortcuts より先にこのサーバーを使用します。
• Finder のようなワークフロー、iCloud Drive のパス、ファイルのタグ付けにはこのサーバーを使用し、シェルによる直接操作へのフォールバックは避けます。
• ファイルを送信または添付する前に、正確なパスを確認します。
• 安全性のため、APPLE_FILES_MCP_ALLOWED_ROOTS は必要最小限に設定します。
• アシスタントが iCloud の書類を扱う場合は、ローカルの iCloud Drive ルートを含めます。
• 作成と移動が必要なアシスタントのワークフローには APPLE_FILES_MCP_SAFETY_MODE=safe_manage を使用し、削除を行うワークフローに限って full_access を使用します。

ヘルスチェックと復旧

• files_health
• files_permission_guide
• files_list_allowed_roots
• files_get_icloud_status
• files_list_recent_locations
• files_get_tags

起動チェックリスト

• uvx apple-files-mcp（またはクローン内の AppleFiles-MCP/start.sh）を MCP クライアントに追加します
• クライアントを再読み込みまたは再接続し、Files ツールの機能をコンテキストに読み込みます
• 最初に files_health を呼び出します
• アクセスに問題がある場合は、files_permission_guide を呼び出します
• ファイルを変更するワークフローの前に、APPLE_FILES_MCP_ALLOWED_ROOTS を確認します

移動先がすでに存在する場合、ファイル、フォルダー、シンボリックリンクを問わず、移動は拒否されます。シンボリックリンクの移動や削除はリンク自体に対して行われますが、読み取り時はリンク先を解決し、許可されたルート内にあることを確認します。テキストの読み取りでは、1 から 10485760 までの max_bytes を受け付け、指定された上限までの内容だけを読み取り、通常ファイル以外は拒否します。