MacOS Defaults

macOS defaults - Model Context Protocol server

python

11

GitHub Stars

python

Language

4 months ago

First Indexed

3 weeks ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "g0t4-mcp-server-macos-defaults": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-macos-defaults",
        "run",
        "mcp-server-macos-defaults"
      ]
    }
  }
}

This MCP server enables reading and writing macOS defaults (settings) from remote clients. It exposes tooling to list domains, search for keys, read domain values, and write values, making macOS defaults manageable from anywhere your MCP ecosystem runs.

How to use

You connect to the macOS defaults MCP server from an MCP client just like you would with any other MCP server. Use the client to list available domains, search for specific words across domains, read values for a domain/key, or write new values back to a domain. The server supports the following operations via the included tools: list-domains (equivalent to defaults domains), find (equivalent to defaults find <word>), defaults-read (equivalent to defaults read <domain> <key>, or the whole domain if you omit the key), and defaults-write (equivalent to defaults write <domain> <key> <value>). When you start a client request, the MCP layer handles the underlying macOS defaults interactions and returns the results to you.

How to install

Prerequisites you need before starting this MCP server are the MCP runtime tools (uv or uvx) available on your system. Use the published or development commands shown below to run the server locally.

Install or ensure the MCP runtime tools are accessible in your environment. The published configuration uses uvx to run the server; the development flow uses uv with a directory flag.
Start the server in development mode (local run) using the directory-based command:

uv --directory /path/to/mcp-server-macos-defaults run mcp-server-macos-defaults

Or start the published, runtime-ready server using uvx with the short form:

uvx mcp-server-macos-defaults

When the server is running, connect your MCP client to the server using the same identifier you configured in your client settings. The client will issue commands to list domains, find keys, read values, or write values as described in the available tools.

Additional configuration and notes

The server exposes two practical ways to run from development or production contexts. In development, you pass the full directory path and a run command to uv. In production, you rely on uvx with the server name as the argument.

Environment variables are not shown in the repository snippet for this server, so no environment variables are specified here. If you have a deployment that requires environment configuration, add the necessary variables in your MCP runtime environment and expose them to the server process as needed.

Tools and capabilities

This server implements a small set of macOS defaults tools to mirror common shell interactions:

list-domains: equivalent to defaults domains to enumerate all domains.
find: equivalent to defaults find <word> to search domains for a word.
defaults-read: equivalent to defaults read <domain> <key>. If no key is provided, reads the entire domain.
defaults-write: equivalent to defaults write <domain> <key> <value> to modify a domain value.

Available tools

list-domains

Lists all macOS domains available in the defaults store, equivalent to running defaults domains.

find

Searches domains for a word, equivalent to running defaults find <word>.

defaults-read

Reads default values from a domain, equivalent to defaults read <domain> <key>. If no key is provided, the entire domain is read.

defaults-write

Writes a value to a domain, equivalent to defaults write <domain> <key> <value>.