Homebrew MCP is a Model Context Protocol (MCP) server for macOS, designed to let users interact with the Homebrew package manager through natural language. It exposes Homebrew commands as MCP tools, enabling MCP-compatible clients such as Claude Desktop to directly call brew functionality to complete tasks such as package management, information queries, and system maintenance.
Main capabilities grouped by function:
- Package management: install, uninstall, upgrade, cleanup
- Information and discovery: list, search, info, outdated, deps
- System health and updates: doctor, update
- Tap and source management: tap, untap
- Version management: pin, unpin
- Service management: services
This server runs real brew commands via subprocess, so Homebrew needs to be installed on macOS. It fully complies with the MCP specification (stdio, JSON-RPC 2.0, MCP spec 2025-06-18) and is designed specifically for Claude Desktop and other LLM clients. The code is written in functional, declarative Python (no classes), and all requests and results are logged to homebrew_mcp.log. The project also includes an interactive test script, test_claude_homebrew_mcp.py, which can dynamically retrieve the tools available on the MCP server, allows Claude to make multiple tool calls for a single user prompt, and demonstrates advanced interaction patterns with the Anthropic API.
Usage:
- Clone the repository: git clone https://github.com/jeannier/homebrew-mcp Then cd homebrew-mcp
- Install uv (if not installed): brew install uv
- Create a virtual environment and install dependencies: uv venv; source .venv/bin/activate; uv pip install -r requirements.txt
- Test running the MCP server locally: uv run python homebrew_mcp.py. After the server starts, it will not output immediately; instead, it silently listens for MCP requests on stdio. You can confirm its running status via homebrew_mcp.log. If integrating with Claude Desktop, there is no need to run this command manually; Claude Desktop will automatically start the server according to the configuration.
Cursor integration:
- Prerequisites: first complete the steps in the installation section to set up the project and dependencies. The "Add to Cursor" button assumes the project is located at ~/Documents/GitHub/homebrew-mcp.
- Install Cursor via Homebrew: brew install --cask cursor
- Click the "Add to Cursor" button, and Cursor will open and automatically install the tools. If the project is not in the assumed location, you need to edit the generated configuration. On macOS, this file is located at ~/.cursor/mcp.json; open it and update the path in the command string in the homebrew-mcp entry. The mcp.json in the repository can be used as a reference.
- After installation, restart Cursor for the tools to take effect.
Claude Desktop integration:
- Install Claude Desktop via Homebrew: brew install --cask claude
- Make sure uv is in PATH and the project is accessible.
- Configure Claude Desktop to use this MCP server: on macOS, edit or create the user-level MCP configuration file ~/Library/Application Support/Claude/claude_desktop.json, add the server definition, and replace /path/to/your/project/ with the absolute path of the cloned project. You can refer to the claud in the repositorye_desktop_config.json example. The --directory parameter tells uv where to find the homebrew_mcp.py script and its context (such as .venv).
- Restart Claude Desktop.
Project structure:
- Python scripts: homebrew_mcp.py (main MCP server script), test_claude_homebrew_mcp.py (interactive Claude integration test script)
- Configuration: claude_desktop_config.json (Claude Desktop example configuration), mcp.json (Cursor example configuration), requirements.txt (Python project dependencies)
- Documentation and metadata: README.md, LICENSE (MIT License), .gitignore
- Generated files (not in Git): .venv/ (Python virtual environment managed by uv), homebrew_mcp.log (MCP server log file)
Monitoring logs: You can view server logs in real time and pretty-print each line of JSON.
Tested environment: This MCP server and its integration with Claude were mainly tested in the following environments: macOS Sonoma 14.7.5, Homebrew 4.5.8, Python 3.13 (managed via uv), mcp module 1.9.4 (installed using uv pip), anthropic module 0.55.0 (installed using uv pip), Claude Desktop 0.10.38 (installed on macOS via Homebrew Cask).
Example prompts:
- Provide a summary of all installed packages
- Check the installed packages and suggest other packages that can be installed
- What is wrong with my Homebrew setup? How can I fix it?
- Show information about the python 3.13 package
- Install the wget package
Interactive Claude test script: Running test_claude_homebrew_mcp.py requires an Anthropic Claude API key, set in the ANTHROPIC_API_KEY variable at the top of the script. This script allows you to interact with Claude, Claude then uses the homebrew_mcp.py server, demonstrating dynamic tool discovery and Claude's ability to make multiple tool calls.
Limitations: This tool only works on macOS and requires Homebrew to be installed beforehand. Using the Claude integration test script requires an Anthropic API key. Other platforms or environments without Homebrew installed are not currently supported.
