mcp-server-macos

An MCP server that lets an AI assistant use your Mac, built on pymacos.

tests
package

Early days. The server works, with two tools to start with. More of pymacos is on its way.

Tools

Every tool tells the client whether it only reads or changes something (the MCP tool annotations), so the client can ask you before a call that does.

Requirements

• macOS. The server starts on other systems, but every tool answers that it needs macOS.
• Python 3.10 or newer.

Installation

The server is launched by your MCP client, which talks to it over stdin and stdout. With uv, there's nothing to install first: uvx mcp-server-macos downloads and runs it.

Claude Code

claude mcp add macos -- uvx mcp-server-macos

Claude Desktop, and other clients configured with JSON

Add the server to the client's configuration (for Claude Desktop, Settings › Developer › Edit Config):

{
  "mcpServers": {
    "macos": {
      "command": "uvx",
      "args": ["mcp-server-macos"]
    }
  }
}

With pip

pip install mcp-server-macos

Then use mcp-server-macos as the command, with no arguments (or python -m mcp_server_macos). If the client doesn't find it, give the command's full path, which which mcp-server-macos prints.

Permissions

macOS grants privacy permissions to the app that runs the server (Claude Desktop, your terminal, your IDE), not to the server. When a tool lacks one, its error says which.

send_notification posts through Script Editor: when notifications are turned off for it in System Settings › Notifications, the tool reports an error instead of sending one that macOS would drop.

Contributing

Bug reports, ideas and pull requests are welcome: see CONTRIBUTING.md, which explains how to add a tool. To report a vulnerability, see SECURITY.md.

License

MIT