How to add Homebrew MCP Python Server to Windsurf

Manage Homebrew packages on macOS from Claude Desktop or Cursor — install, upgrade, search, and maintain. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 29★ · stdio · no auth

Windsurf config for Homebrew MCP Python Server

git clone https://github.com/jeannier/homebrew-mcp

{
  "mcpServers": {
    "homebrew-mcp-python-server": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/project/",
        "homebrew_mcp.py"
      ]
    }
  }
}

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Homebrew MCP Python Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Homebrew MCP Python Server's tools become available to Cascade.

Before you start

macOS
Homebrew installed
Python 3.13
uv (install via: brew install uv)
An MCP client such as Claude Desktop or Cursor

What Homebrew MCP Python Server can do in Windsurf

install

Install a Homebrew package (runs brew install).

uninstall

Uninstall a Homebrew package (runs brew uninstall).

upgrade

Upgrade installed package(s) to the latest version (runs brew upgrade).

cleanup

Remove old versions and clean up cached downloads (runs brew cleanup).

list

List installed formulae and casks (runs brew list).

search

Search for available packages (runs brew search).

info

Show information about a package (runs brew info).

outdated

List installed packages that have newer versions available (runs brew outdated).

Security

Runs real `brew` commands via subprocess on your machine, including `install`, `uninstall`, `upgrade`, and `cleanup` — these mutate your system's installed packages. macOS only; requires Homebrew. No authentication or API key is required by the server itself.

Homebrew MCP Python Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Homebrew MCP Python Server config there under the "mcpServers" key and restart the client.

Is Homebrew MCP Python Server safe to use with Windsurf?

What platforms are supported?

macOS only. The server runs real `brew` commands via subprocess and requires Homebrew to be installed.

Does it require an API key?

No. The MCP server itself needs no authentication. An Anthropic API key is only needed if you run the optional interactive test script (test_claude_homebrew_mcp.py).

How do I add it to Claude Desktop?

Clone the repo and set up the uv venv, then add an entry under mcpServers in ~/Library/Application Support/Claude/claude_desktop.json with command 'uv' and args ['run', '--directory', '/path/to/your/project/', 'homebrew_mcp.py'], using the absolute path to your clone. Restart Claude Desktop.

View repo Full Homebrew MCP Python Server page