home / mcp / homebrew mcp python server
Exposes Homebrew commands as MCP tools to manage macOS packages via MCP clients.
Configuration
View docs{
"mcpServers": {
"jeannier-homebrew-mcp": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/your/project/",
"homebrew_mcp.py"
]
}
}
}You run a Python-based MCP server that exposes Homebrew commands as MCP tools, enabling Claude Desktop and other MCP clients to manage macOS packages via a standardized, JSON-RPC style interface over stdio. This server design makes it easy to discover and invoke Homebrew actions from your conversational or automated workflows while keeping logs and integration details organized.
Start by ensuring the MCP server is reachable by your MCP client. This server runs over stdio, so it communicates with the client through standard input and output streams. Your client should dynamically discover available tools, then call the specific tool you want (for example, to install or list packages). All requests and results are logged to a file for auditing and debugging.
# Prerequisites
- macOS with Homebrew installed
- Python 3.13
- uv (Python virtual environment manager)
# 1) Clone the project
git clone https://github.com/jeannier/homebrew-mcp
cd homebrew-mcp
# 2) Install uv if not already installed
brew install uv
# 3) Create a virtual environment and install dependencies
uv venv
source .venv/bin/activate # Activate the virtual environment
uv pip install -r requirements.txt
# 4) Run the MCP Server for local testing
uv run python homebrew_mcp.pyConfiguration and integration details are provided below so you can connect Claude Desktop or Cursor to your MCP server and confirm everything is running smoothly.
Cursor integration is optional but convenient on macOS. If you want to use Cursor, install it and add the tool to Cursor so it launches your MCP server with the correct working directory.
Claude Desktop integration lets Claude call MCP tools directly. Install Claude Desktop, ensure uv is on your PATH, and point Claude Desktop to run the MCP server using uv with the directory of your project.
You can monitor server activity in real time by tailing the log file that records all requests and results.
- The server is designed to run locally for testing and development. It starts silently and writes details to a log file when it receives requests.
- If Claude Desktop starts the server automatically, make sure the configured directory path points to your project location where homebrew_mcp.py resides.
- If you need to validate connectivity, try a simple tool discovery call from your MCP client and then invoke a common action like install or list.
- Discover tools dynamically, then request a specific action such as installing, upgrading, or listing Homebrew packages.
- Use the log file homebrew_mcp.log to review what happened for each request and outcome, which helps with debugging and auditing.
tail -f homebrew_mcp.log | jq .Install a Homebrew package. Install the specified formula and make it available for use in subsequent commands.
Remove a package installed via Homebrew. Cleans up the package from the system.
Upgrade an installed package to the latest available version.
Clean up cached files and outdated versions to free disk space.
List all installed Homebrew packages currently on the system.
Search the Homebrew repository for packages by name or description.
Show detailed information about a specific Homebrew package.
Identify packages that have newer versions available.
Display dependencies for a given package.
Run a diagnostic to identify issues with the Homebrew setup and provide guidance to fix them.
Update Homebrew itself and the local package metadata.
Add a new tap (repository) to Homebrew to access more packages.
Remove a previously added tap from Homebrew.
Pin a package to prevent it from being upgraded automatically.
Unpin a package to allow automatic upgrades again.
Manage macOS services related to Homebrew-installed packages.