apple-files-mcp 1.0.0__tar.gz

apple_files_mcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Apple MCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

apple_files_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: apple-files-mcp
+Version: 1.0.0
+Summary: Local Apple Files MCP server for macOS
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/JonathanRReed/Apple-MCPs
+Project-URL: Repository, https://github.com/JonathanRReed/Apple-MCPs
+Project-URL: Changelog, https://github.com/JonathanRReed/Apple-MCPs/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/JonathanRReed/Apple-MCPs/issues
+Keywords: mcp,model-context-protocol,macos,apple,ai-agent,automation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: apple-mcp-common<2,>=1.0.0
+Requires-Dist: mcp<3,>=2.0.0
+Requires-Dist: pydantic>=2.12.0
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: ruff<1,>=0.12; extra == "dev"
+Dynamic: license-file
+
+<!-- mcp-name: io.github.jonathanrreed/apple-files-mcp -->
+
+# Apple Files MCP
+
+Local MCP server for file, Finder-adjacent, and iCloud Drive workflows on macOS.
+
+## Capabilities
+
+- list allowed file roots
+- inspect directory contents
+- search files and folders by name
+- read UTF-8 text files
+- inspect file metadata
+- list recent files
+- open a path in the default app
+- reveal a path in Finder
+- read and write Finder tags
+- list recent locations
+- report local iCloud Drive availability
+- create folders
+- move or rename paths
+- delete files or empty folders
+- resources: `files://allowed-roots`, `files://recent`, `files://recent-locations`, `files://icloud-status`
+- prompts: `files_prepare_attachment`, `files_organize_workspace`
+- tool discovery helpers `search_tools` and `get_tool_info` for context-constrained clients
+
+## Install On This Mac
+
+<details>
+<summary>Quick start (uvx, from PyPI)</summary>
+
+With [uv](https://docs.astral.sh/uv/getting-started/installation/) installed:
+
+```bash
+uvx apple-files-mcp
+```
+
+No clone, no venv management.
+
+</details>
+
+<details>
+<summary>From a clone</summary>
+
+```bash
+git clone https://github.com/JonathanRReed/Apple-MCPs.git
+cd Apple-MCPs
+uv sync --all-packages
+```
+
+This builds one workspace environment with every server's entry point in `.venv/bin` (for example `.venv/bin/apple-files-mcp`). You can also point an MCP client at `AppleFiles-MCP/start.sh`, which prefers `uv run` and falls back to a plain venv bootstrap (Python 3.11+ required).
+
+</details>
+
+## Install In AI Agents
+
+```json
+{
+  "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"
+      }
+    }
+  }
+}
+```
+
+Running from a clone instead? Use `/path/to/Apple-MCPs/AppleFiles-MCP/start.sh` as the command with empty `args`.
+
+Claude Code:
+
+```bash
+claude mcp add --transport stdio --scope project apple-files -- uvx apple-files-mcp
+```
+
+## Transport
+
+`stdio` is the default and recommended transport. Set `APPLE_FILES_MCP_TRANSPORT=streamable-http` (with optional `APPLE_FILES_MCP_HOST` and `APPLE_FILES_MCP_PORT`) to serve Streamable HTTP instead.
+
+## Prompting Notes
+
+- `tools/list` returns the full Files tool surface. Context-constrained clients can use `search_tools` first, then `get_tool_info` for the Files tool they need.
+- Use this server before Mail, Messages, Notes, or Shortcuts when the user references a local file or attachment.
+- Use this server for Finder-style workflows, iCloud Drive paths, and file tagging, not raw shell fallbacks.
+- Confirm the exact path before sending or attaching a file.
+- Keep `APPLE_FILES_MCP_ALLOWED_ROOTS` narrow for safety.
+- Include the local iCloud Drive root when you want the assistant to work with iCloud documents.
+- Use `APPLE_FILES_MCP_SAFETY_MODE=safe_manage` for assistant workflows that need create and move, and `full_access` only for delete workflows.
+
+## Health And Recovery
+
+- `files_health`
+- `files_permission_guide`
+- `files_list_allowed_roots`
+- `files_get_icloud_status`
+- `files_list_recent_locations`
+- `files_get_tags`
+
+## Launch Checklist
+
+- Add `uvx apple-files-mcp` (or a clone's `AppleFiles-MCP/start.sh`) to your MCP client
+- Reload or reconnect the client so the Files tool surface is loaded into context
+- Call `files_health` first
+- If access looks wrong, call `files_permission_guide`
+- Confirm `APPLE_FILES_MCP_ALLOWED_ROOTS` before any file mutation workflow

apple_files_mcp-1.0.0/README.md

@@ -0,0 +1,109 @@
+<!-- mcp-name: io.github.jonathanrreed/apple-files-mcp -->
+
+# Apple Files MCP
+
+Local MCP server for file, Finder-adjacent, and iCloud Drive workflows on macOS.
+
+## Capabilities
+
+- list allowed file roots
+- inspect directory contents
+- search files and folders by name
+- read UTF-8 text files
+- inspect file metadata
+- list recent files
+- open a path in the default app
+- reveal a path in Finder
+- read and write Finder tags
+- list recent locations
+- report local iCloud Drive availability
+- create folders
+- move or rename paths
+- delete files or empty folders
+- resources: `files://allowed-roots`, `files://recent`, `files://recent-locations`, `files://icloud-status`
+- prompts: `files_prepare_attachment`, `files_organize_workspace`
+- tool discovery helpers `search_tools` and `get_tool_info` for context-constrained clients
+
+## Install On This Mac
+
+<details>
+<summary>Quick start (uvx, from PyPI)</summary>
+
+With [uv](https://docs.astral.sh/uv/getting-started/installation/) installed:
+
+```bash
+uvx apple-files-mcp
+```
+
+No clone, no venv management.
+
+</details>
+
+<details>
+<summary>From a clone</summary>
+
+```bash
+git clone https://github.com/JonathanRReed/Apple-MCPs.git
+cd Apple-MCPs
+uv sync --all-packages
+```
+
+This builds one workspace environment with every server's entry point in `.venv/bin` (for example `.venv/bin/apple-files-mcp`). You can also point an MCP client at `AppleFiles-MCP/start.sh`, which prefers `uv run` and falls back to a plain venv bootstrap (Python 3.11+ required).
+
+</details>
+
+## Install In AI Agents
+
+```json
+{
+  "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"
+      }
+    }
+  }
+}
+```
+
+Running from a clone instead? Use `/path/to/Apple-MCPs/AppleFiles-MCP/start.sh` as the command with empty `args`.
+
+Claude Code:
+
+```bash
+claude mcp add --transport stdio --scope project apple-files -- uvx apple-files-mcp
+```
+
+## Transport
+
+`stdio` is the default and recommended transport. Set `APPLE_FILES_MCP_TRANSPORT=streamable-http` (with optional `APPLE_FILES_MCP_HOST` and `APPLE_FILES_MCP_PORT`) to serve Streamable HTTP instead.
+
+## Prompting Notes
+
+- `tools/list` returns the full Files tool surface. Context-constrained clients can use `search_tools` first, then `get_tool_info` for the Files tool they need.
+- Use this server before Mail, Messages, Notes, or Shortcuts when the user references a local file or attachment.
+- Use this server for Finder-style workflows, iCloud Drive paths, and file tagging, not raw shell fallbacks.
+- Confirm the exact path before sending or attaching a file.
+- Keep `APPLE_FILES_MCP_ALLOWED_ROOTS` narrow for safety.
+- Include the local iCloud Drive root when you want the assistant to work with iCloud documents.
+- Use `APPLE_FILES_MCP_SAFETY_MODE=safe_manage` for assistant workflows that need create and move, and `full_access` only for delete workflows.
+
+## Health And Recovery
+
+- `files_health`
+- `files_permission_guide`
+- `files_list_allowed_roots`
+- `files_get_icloud_status`
+- `files_list_recent_locations`
+- `files_get_tags`
+
+## Launch Checklist
+
+- Add `uvx apple-files-mcp` (or a clone's `AppleFiles-MCP/start.sh`) to your MCP client
+- Reload or reconnect the client so the Files tool surface is loaded into context
+- Call `files_health` first
+- If access looks wrong, call `files_permission_guide`
+- Confirm `APPLE_FILES_MCP_ALLOWED_ROOTS` before any file mutation workflow

apple_files_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "apple-files-mcp"
+version = "1.0.0"
+description = "Local Apple Files MCP server for macOS"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = ["mcp", "model-context-protocol", "macos", "apple", "ai-agent", "automation"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Environment :: MacOS X",
+  "Intended Audience :: Developers",
+  "Operating System :: MacOS",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "apple-mcp-common>=1.0.0,<2",
+  "mcp>=2.0.0,<3",
+  "pydantic>=2.12.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/JonathanRReed/Apple-MCPs"
+Repository = "https://github.com/JonathanRReed/Apple-MCPs"
+Changelog = "https://github.com/JonathanRReed/Apple-MCPs/blob/main/CHANGELOG.md"
+Issues = "https://github.com/JonathanRReed/Apple-MCPs/issues"
+
+[project.scripts]
+apple-files-mcp = "apple_files_mcp.tools:main"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8,<10",
+  "ruff>=0.12,<1",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.uv.sources]
+apple-mcp-common = { workspace = true }

apple_files_mcp-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

apple_files_mcp-1.0.0/src/apple_files_mcp/__init__.py

@@ -0,0 +1 @@
+"""Apple Files MCP package."""

apple_files_mcp-1.0.0/src/apple_files_mcp/config.py

@@ -0,0 +1,62 @@
+import os
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Settings:
+    server_name: str
+    version: str
+    safety_mode: str
+    allowed_roots: tuple[Path, ...]
+    transport: str
+    host: str
+    port: int
+    log_level: str
+
+
+def _parse_int(value: str | None, default: int) -> int:
+    if value is None:
+        return default
+    try:
+        return int(value)
+    except ValueError:
+        return default
+
+
+def _default_roots() -> tuple[Path, ...]:
+    home = Path.home()
+    candidates = (
+        home / "Desktop",
+        home / "Documents",
+        home / "Downloads",
+        home / "Library" / "Mobile Documents" / "com~apple~CloudDocs",
+    )
+    existing = [path for path in candidates if path.exists()]
+    return tuple(existing or [home / "Downloads"])
+
+
+def _parse_roots(value: str | None) -> tuple[Path, ...]:
+    if not value:
+        return _default_roots()
+    roots = []
+    for raw in value.split(","):
+        path = Path(raw.strip()).expanduser()
+        if raw.strip():
+            roots.append(path)
+    return tuple(roots) or _default_roots()
+
+
+@lru_cache(maxsize=1)
+def load_settings() -> Settings:
+    return Settings(
+        server_name="Apple Files MCP",
+        version="0.1.0",
+        safety_mode=os.environ.get("APPLE_FILES_MCP_SAFETY_MODE", "safe_manage").strip().lower() or "safe_manage",
+        allowed_roots=_parse_roots(os.environ.get("APPLE_FILES_MCP_ALLOWED_ROOTS")),
+        transport=os.environ.get("APPLE_FILES_MCP_TRANSPORT", "stdio").strip().lower() or "stdio",
+        host=os.environ.get("APPLE_FILES_MCP_HOST", "127.0.0.1"),
+        port=_parse_int(os.environ.get("APPLE_FILES_MCP_PORT"), 8000),
+        log_level=os.environ.get("APPLE_FILES_MCP_LOG_LEVEL", "INFO").strip().upper() or "INFO",
+    )