Use OneMacTools as an MCP server for Claude, Claude Code, Cursor and Codex

What the OneMacTools MCP server does

The Model Context Protocol (MCP) is the standard way AI assistants use apps and tools. OneMacTools includes an MCP server, so an assistant you already use can answer questions like “what's on port 3000?”, “what's taking space in my home folder?” or “when does my passport expire?” from what OneMacTools knows about your Mac, and can ask OneMacTools to run tools such as Compress PDF or Transcribe on your files.

The server is the OneMacTools app itself, started by the assistant with the --mcp argument. It talks to the assistant over standard input and output, so no network port is opened and nothing is uploaded. It shows no window of its own; when an assistant asks for an action, the main OneMacTools app opens an approval window (opening itself in the background if it wasn't running).

It's off until you turn it on, and it needs an activated licence. If either is missing, the assistant gets a plain message saying so instead of any data.

Which AI assistants OneMacTools can set up

Settings › AI Assistants has a row for each assistant OneMacTools can configure for you, and a snippet for everything else:

A row's Add to … button is greyed out when that assistant doesn't seem to be installed (OneMacTools looks for its app or its settings folder). Hover over the button to see which file it will change.

How to connect Claude, Cursor or Codex to your Mac

1. Open OneMacTools and choose OneMacTools › Settings (⌘,).
2. Scroll to AI Assistants and turn on Let AI assistants use OneMacTools.
3. Click Add to Claude Desktop… (or Claude Code, Cursor or Codex).
4. Read the confirmation: “OneMacTools adds an entry called “onemactools” to … after backing the file up. Nothing else in it changes.” Click Add.
5. The row now shows Added with a green tick, and a line under the section tells you what to do next, such as “Quit and reopen Claude to load it.” It also names the backup file if there was an existing one.
6. Restart or reload the assistant as described, then ask it something like “Use OneMacTools to tell me how my Mac is doing.”

Adding to an assistant also turns on Let AI assistants use OneMacTools if it was off. If you move OneMacTools to a different folder, click Update next to the assistant so the entry points to the app's new location.

Manual MCP config for other assistants

For any other assistant that supports MCP over stdio, click Copy Setup Snippet next to Other assistants and paste it into that assistant's MCP settings. The snippet is the same entry OneMacTools writes for Claude and Cursor:

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

The command is the path to the app on your Mac, so the copied snippet always has the right path even if you keep OneMacTools somewhere other than Applications. For Claude Code the entry also has "type": "stdio". Codex uses TOML instead of JSON, so its entry is a table:

[mcp_servers.onemactools] followed by command = "/Applications/OneMacTools.app/Contents/MacOS/OneMacTools" and args = ["--mcp"].

OneMacTools recognises the assistant from its name when it connects and uses that name in approval windows and History: Claude, Claude Code, Cursor, Codex, Windsurf, Gemini CLI or VS Code, or the name the assistant reports.

What an assistant can read without asking

Read tools answer straight away, because they only look. They're marked read-only to the assistant:

Paper summaries never include ID, card or account numbers; life_admin reports how many files hold them and their names only. Reading a document's actual text is an action and always asks. More on this in AI assistant permissions and approvals. The Files-based tools depend on Files and Life Admin.

What an assistant must ask you for

These tools change something, so each one opens an approval window in OneMacTools and waits for you to click Allow:

• run_tool: run any OneMacTools tool on files or text, with options. Results go to a new folder; originals aren't changed. Tools that need you at the Mac, such as Screen Recorder or Record Meeting, can't be run by an assistant.
• quit_app: quit an app the normal way, so it can ask to save. Finder can't be quit this way.
• stop_process and stop_agent_session: stop one of your own processes, or an AI agent session and everything it started.
• stop_container: stop a running Docker container.
• start_recording and stop_recording: record the Mac second by second, then get what peaked and which apps were behind it.
• read_document: give the assistant the text of one document.
• move_to_trash: move files in your home folder to the Trash, never delete them.

Example prompts to try

• “Why is my Mac slow right now?” (uses mac_health and list_apps)
• “What's running on port 5173, and which project started it? Stop it.” (reads with whats_on_port, then asks to stop_process)
• “Which of my projects have old node_modules folders, and how much space would I get back?”
• “Record my Mac while I run this build, then tell me what peaked.”
• “Find the PDFs I downloaded from Gmail this week and merge them.” (finds with find_files, then asks to run_tool)
• “How much did I spend on Amazon last month?” (needs Files)
• “Compress these three screenshots to JPEG.” (run_tool with Compress Images)

For general background on ports and agents, see the guide What's using a port on my Mac? and the Dev & Agents docs.

How to turn the MCP server off

Turn off Let AI assistants use OneMacTools in Settings › AI Assistants. Assistants that still have the entry can start the server, but every read and action gets the reply “OneMacTools isn't letting AI assistants in” and nothing else.

To remove OneMacTools from an assistant completely, delete the onemactools entry from its settings file (the paths are in the table above), or restore the backup OneMacTools made. Quitting the assistant ends the server process too.

Questions

Related docs