Can finder_list see folders outside my home directory?

Yes. It does a direct directory listing at any absolute path, so it works for system folders, mounted volumes and external drives like /Volumes/Backup — places Spotlight may not index. macOS permission prompts still apply for protected locations.

Does finder_list change or delete any files?

No. It is a read-only tool that only lists the files and folders at the path you give it. To move, rename, open or delete items, the AI uses separate LMCP tools, each with its own confirmation.

Do I need an API key or cloud account?

No. LMCP is free and runs natively on your Mac with no API keys. Desktop clients connect over local stdio and web AIs connect through the LMCP Cloud Relay, but the directory listing always happens locally on your machine.

List Files at Any Path on Mac with AI

The finder_list tool lets your AI assistant list the files and folders at any absolute path on your Mac. Unlike Spotlight-based search, it reads the directory directly, so it works for paths outside your home folder too — like /Volumes/Backup, /Library or an external drive. You just type something natural like: "List everything in /Users/me/Projects/2026-launch and tell me which folders haven't been touched recently." The AI calls finder_list, gets the real contents of that directory, and answers.

Because it's a read-only listing, nothing is modified — it's the safe first step for any file workflow. Download LMCP to enable it. LMCP is a free, native macOS MCP server with 150+ tools that connect your AI to your real Mac apps.

Which AI agents work?

Pretty much every major AI client works with finder_list through LMCP:

Desktop clients — Claude Desktop, Cursor, VS Code (GitHub Copilot), Windsurf and Zed auto-configure over a local stdio connection. No keys, no setup beyond installing LMCP.
Web AIs — ChatGPT, Claude.ai (web), Grok and Perplexity connect through the LMCP Cloud Relay connector, which securely bridges the web assistant to the LMCP server running on your Mac.

Whichever you use, the directory listing happens locally on your machine.

Automation

finder_list is the discovery step that feeds richer file workflows. Common chains:

List a folder, then read the contents of the most relevant file to summarize it.
List a folder, then move or rename stale items into an archive subfolder.
List a Downloads or Desktop directory, then open a specific match in Finder.
Walk a project tree folder by folder to build an inventory or find duplicates.

Because the AI sees real paths and names, each follow-up step targets exactly the right file.

Context

The AI isn't guessing or working from a stale index — it sees the actual current state of your disk. If you just dropped three files into a folder a second ago, finder_list returns them. That live, on-disk truth means answers like "which of these is the newest export" or "is the invoice already in this folder" are grounded in your real Mac data, not a cached snapshot.

Productivity

Instead of switching to Finder, navigating a deep path, sorting columns and eyeballing the list, you ask once in plain language and get a clean, filtered answer. Asking "what PDFs are in my contracts folder and which were added this month" is a single sentence instead of a manual hunt. For paths outside Spotlight's reach — system folders, mounted volumes, external drives — it's often faster than the GUI, and it lets the AI keep moving straight into the next action without you copy-pasting filenames.

Privacy & GDPR

Everything runs locally on your Mac. finder_list reads your directory on-device and returns the result to your AI session — no file names, no paths and no contents are copied to any LMCP server or third-party cloud. There are no API keys and nothing is stored remotely. This local-first design is GDPR-compliant by architecture: see GDPR-compliant by architecture for the full picture. Your data stays where it belongs — on your machine.