mcp-macos-toolkit

Local-first macOS tools for MCP: search your Mac, run approved Shortcuts, manage Homebrew, and work with local models without turning your agent into an unrestricted shell.

Status: early access / active development (v0.1.0). The public interface is being stabilized. Review tool inputs before approving calls, keep mutation flags off unless needed, and report rough edges through GitHub Issues.

Why This Exists

macOS already has useful automation, package-management, productivity, and local-AI tools. They are usually exposed one command at a time. mcp-macos-toolkit gives MCP clients one bounded stdio server with explicit schemas, local-only data paths, and opt-in mutation controls.

The V1 interface is organized into five groups:

Arbitrary shell commands and arbitrary AppleScript are intentionally out of scope.

For a curated set of modern macOS command-line tools, pair this server with homebrew-cli-toolbelt. The toolbelt answers what should I install?; this MCP server provides bounded discovery and one-package-at-a-time installation without running the toolbelt's interactive installer or any remote shell script.

V0.1 Tool Surface

Related MCP server: local-mmcp

Quick Start From Source

Requirements:

• macOS on Apple Silicon

• Node.js 22 or newer; CI verifies Node.js 22 and 24

• npm

git clone https://github.com/ContractorKeith/mcp-macos-toolkit.git
cd mcp-macos-toolkit
npm ci
npm run check
npm run build
node dist/cli.js doctor

Point your MCP client at the compiled entrypoint using an absolute path:

{
  "mcpServers": {
    "macos-toolkit": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-macos-toolkit/dist/cli.js"],
      "env": {
        "MCP_MACOS_ALLOWED_ROOTS": "/Users/you/Documents:/Users/you/Projects"
      }
    }
  }
}

Ready-to-edit configurations are in examples/. This repository does not currently promise an npm-hosted install path; use a source checkout until a package release is announced.

Safe Configuration

The launch directory is the only allowed filesystem root when MCP_MACOS_ALLOWED_ROOTS is unset. Add the smallest roots that cover the work you want the agent to do.

Every write or mutation call also requires confirm=true. The environment flag is a server-owner control; confirm=true is a per-call acknowledgment. Both must be present.

Start read-only, then enable one capability for one session. For example:

{
  "env": {
    "MCP_MACOS_ALLOWED_ROOTS": "/Users/you/Projects",
    "MCP_MACOS_ALLOWED_SHORTCUTS": "Start Focus Timer,Open Project Notes",
    "MCP_MACOS_ALLOW_SHORTCUTS": "true"
  }
}

See Permissions for macOS Privacy & Security settings and Security Model for the complete trust boundary.

Example Prompts

Once connected to an MCP client, try read-only requests first:

Show me the allowed filesystem roots, then find Markdown files mentioning release checklists.

List my outdated Homebrew formulae. Do not install or upgrade anything.

Show the local Ollama and MLX models and any currently running Ollama models.

For Shortcuts, Calendar, Reminders, package changes, model runs, or quantization, inspect the proposed tool input before approving it.

Optional MLX Semantic Search

Text search works without MLX. Semantic search is optional and remains local to the configured Python environment.

1. Create or select a Python environment with the required MLX embedding dependencies.

2. Set MCP_MACOS_MLX_PYTHON to its absolute Python executable.

3. Optionally change MCP_MACOS_MLX_EMBED_MODEL.

4. Download the selected model in that Python environment yourself after reviewing its source and disk requirements.

The default embedding model is mlx-community/all-MiniLM-L6-v2-4bit. The server forces the embedding helper into offline mode: it does not silently download a model or fall back to a cloud API.

Development

npm ci
npm run format:check
npm run lint
npm run typecheck
npm test
npm run build

Run the complete local gate with:

npm run check

The official MCP SDK is pinned to the V1 production line. The server logic is separated from stdio transport so adapters and safety policy can be tested without granting CI runners access to personal macOS data.

See Architecture, Contributing, and the product specification.

Security

mcp-macos-toolkit is a local stdio server. It does not provide a hosted service or telemetry endpoint. It can still reach sensitive local data and invoke powerful system tools when you enable those capabilities.

• Keep allowed roots narrow.

• Never enable mutation flags you do not need.

• Treat file contents and tool output as untrusted input to the model.

• Review confirm=true calls before approving them.

• Do not expose the stdio process through an unauthenticated network bridge.

Report vulnerabilities privately as described in SECURITY.md.

Limitations

• macOS only; V1 targets Apple Silicon.

• macOS permissions are granted to the application hosting the MCP process, not to this repository in the abstract.

• Calendar and Reminders behavior depends on local account configuration and macOS privacy grants.

• Semantic search and MLX operations require separately installed local Python dependencies and model files.

• Long-running model operations can consume substantial memory, storage, and battery.

• This project cannot guarantee that an MCP client will display or enforce tool annotations correctly.

Contributing

Bug reports, focused tool additions, permission-flow improvements, tests, and documentation fixes are welcome. Read CONTRIBUTING.md and follow the Code of Conduct.

License

MIT. See LICENSE.