MCP (AI Plugin)

What is the MCP (AI Plugin)?

Owlfiles includes a built-in MCP server using the Model Context Protocol. It lets an AI agent such as Claude Desktop, Claude Code, or Codex access files through Owlfiles.

Once connected, you can ask the agent in plain language to list files in Google Drive, copy a report from your NAS to Dropbox, or find invoices on an SMB server. The agent uses Owlfiles to carry out the request across local disks, SMB, FTP, SFTP, WebDAV, NFS, and supported cloud services.

What the agent can do

The Owlfiles MCP server exposes these tools:

• list_connections — list configured Owlfiles connections.
• list_dir — list the contents of a folder.
• get_item_metadata — get the size, type, and modified date of a file or folder.
• search_files — search for files and folders by name.
• read_file — read file contents, including large files in chunks.
• write_file — create or overwrite a file, including large uploads in chunks.
• create_folder — create a folder.
• copy_item — copy a file or folder, including between two connections.
• move_item — move or rename a file or folder, including across connections.
• delete_item — delete a file or folder.

Because copy and move work across connections, the agent can transfer files directly between a NAS and a cloud drive.

Set up the connection

Open Settings → MCP (AI Plugin) in Owlfiles. Claude Desktop, Claude Code, and Codex offer a guided installation. Other MCP-compatible tools can be configured manually.

Claude Desktop

1. Click Install to Claude Desktop.
2. Owlfiles builds an owlfiles.mcpb extension package and opens it in Claude Desktop.
3. Click Install in the dialog shown by Claude Desktop.
4. Start a new chat to use the Owlfiles tools.

Claude Code

1. Click Install to Claude Code.
2. Copy the claude mcp add command shown by Owlfiles.
3. Open Terminal, paste the command, and press Return.
4. Start or restart Claude Code.

Codex

1. Make sure Codex is installed.
2. Click Install to Codex.
3. If prompted, grant access to ~/.codex/config.toml. Owlfiles adds an [mcp_servers.owlfiles] entry.
4. Restart Codex to apply the change.

Other AI agents

Any MCP-compatible tool can use the Owlfiles MCP server. The server type is stdio. Add this entry to the tool’s MCP configuration and restart the agent:

{
  "mcpServers": {
    "owlfiles": {
      "command": "/Applications/Owlfiles.app/Contents/MacOS/Owlfiles",
      "args": ["--mcp"]
    }
  }
}

Privacy and security

• The MCP server runs locally on your Mac and is launched by the AI agent only when needed. It does not open a network port.
• It reuses connections, accounts, and saved credentials already stored in Owlfiles. Passwords and tokens are not sent to the agent.
• Owlfiles runs in the macOS App Sandbox. The agent can access local folders only after you have granted Owlfiles access to them.
• An agent can delete, overwrite, and move files. Review destructive actions before approving them.

Troubleshooting

A connection asks me to sign in

Open that connection once in Owlfiles and sign in. The MCP server will reuse the saved login.

The agent cannot reach a local folder

Open the folder once in Owlfiles to grant access, then try again. This sandbox restriction affects local files, not remote or cloud connections.

The plugin stopped responding

Restart your AI agent. The agent manages the MCP server process and will launch it again automatically.