mcp -macos-defaults

This MCP server provides tooling to read and write macOS defaults using the standard macOS defaults command under an MCP server interface. It exposes four tools: list-domains (equivalent to defaults domains), find (equivalent to defaults find <word>), defaults-read (equivalent to defaults read <domain> [<key>]), and defaults-write (equivalent to defaults write <domain> <key> <value>). Start the server using the published configuration (uvx mcp-server-macos-defaults) and then invoke the tools via the MCP interface. These tools allow you to inspect, search, and modify macOS user defaults programmatically, which is useful for automation, tooling, or integration with other MCP-enabled clients. The environment is designed for macOS environments where the defaults system is available.

Prerequisites:

• macOS system with access to the defaults command
• Python 3.x and the uv tooling (the UV ecosystem) installed on your machine
• Internet access to install or build MCP server packages, if starting from source

Option A — Install and run the published server (recommended):

1. Ensure uv (the UV tool) and uvx are installed on your system. If you don’t have UV installed, follow the project’s installation instructions to install the UV toolchain.

2. Start the MCP server using the published configuration:

   uvx mcp-server-macos-defaults

   This runs the server in its published form, exposing the four tools for macOS defaults.

Option B — Develop locally from source:

1. Clone the repository containing mcp-server-macos-defaults.

2. Install development dependencies using UV tooling:

   uv sync uv build

   This prepares the package for distribution in dist/ (or equivalent build output).

3. Run in development mode (example; adjust to your local path):

   uv run mcp-server-macos-defaults

4. If you plan to publish, follow the project’s publishing steps (e.g., uv publish) and provide credentials as required (e.g., PyPI credentials for Python-based servers).

Note: The development configuration shown in the README indicates a directory-based run during development and a module-based run for published servers. Ensure you use the appropriate command for your workflow.

Tips and caveats:

• This server interacts with macOS defaults, so it should be run on macOS where the defaults command is available.
• Debugging MCP servers can be challenging since they run over stdio. If issues arise, use the MCP Inspector tool to observe IO and protocol interactions. The Inspector can be launched via npm and used with the uv run configuration to view a debugging URL in a browser.
• If you are testing changes locally, use the development configuration (directory-based) to run the server while you’re actively developing.
• No specific environment variables are required for the published server, but if you extend or customize the server, you may need to set environment variables for authentication, paths, or defaults scopes.
• When using defaults-read, provide the domain and key as needed. If only a domain is supplied, the entire domain will be read.
• When using defaults-write, ensure your values are properly quoted and escaped to avoid shell interpretation issues.
• If you encounter permission-related issues, ensure you have the appropriate macOS permissions to access and modify the target domains.