Enables package management operations on macOS including installing, uninstalling, upgrading, searching, and listing packages, as well as system diagnostics through Homebrew's doctor command.
Provides Homebrew package management tools specifically optimized for macOS, allowing AI agents to manage software installations and system maintenance on macOS systems.
Homebrew MCP Python Server
A Model Context Protocol (MCP) server for Homebrew package management on macOS, designed for seamless integration with Claude Desktop and other MCP-compatible clients.
- Language: Python 3.13
- MCP: Model Context Protocol
- Package Manager: Homebrew (macOS)
- Venv/Dependency Manager: uv
Features
- Exposes Homebrew commands as MCP tools. The supported commands are grouped by function:
- Package Management:
install
,uninstall
,upgrade
,cleanup
- Information & Discovery:
list
,search
,info
,outdated
,deps
- System Health & Updates:
doctor
,update
- Tap & Source Management:
tap
,untap
- Version Management:
pin
,unpin
- Service Management:
services
- Package Management:
- Runs real
brew
commands via subprocess (requires Homebrew on macOS). - Fully MCP spec-compliant (stdio, JSON-RPC 2.0, MCP spec 2025-06-18).
- Designed for Claude Desktop and other LLM clients.
- Functional, declarative Python (no classes).
- Logs all requests/results to
homebrew_mcp.log
. - Includes an interactive test script (
test_claude_homebrew_mcp.py
) that:- Dynamically fetches available tools from the MCP server.
- Allows Claude to make multiple tool calls for a single user prompt.
- Demonstrates advanced interaction patterns with the Anthropic API.
Installation
- Clone this repository:
- Install uv (if not already):
- Create a virtual environment and install dependencies:
- Run the MCP Server (for Local Testing):
To test the server locally or during development, you can run it directly:The server will then start. If successful, there will be no immediate output; it will silently listen for MCP requests over stdio. You can confirm it's running by checking the
homebrew_mcp.log
file.Note: If you are integrating with Claude Desktop, you do not need to run this command manually. Claude Desktop will start the server automatically based on the configuration provided in the "Claude Desktop Integration" section. This command is for direct testing or development purposes.
Cursor Integration
Prerequisite: Before adding the tool, please complete the steps in the Installation section to set up the project and its dependencies. The "Add to Cursor" button assumes the project is located at ~/Documents/GitHub/homebrew-mcp
.
- Install Cursor via Homebrew (macOS):
- Add the Tool to Cursor:
- Click the "Add to Cursor" button above. This will open Cursor and automatically install the tool.
- If your project is not at the location assumed by the button, you will need to edit the generated configuration. On macOS, this file is located at
~/.cursor/mcp.json
. Open it and update the path inside thecommand
string for thehomebrew-mcp
entry. Themcp.json
file in this repository can be used as a reference.
- Restart Cursor:
- For the tool to become active, restart Cursor after installation.
Claude Desktop Integration
- Install Claude Desktop via Homebrew (macOS):
- Ensure
uv
is in your PATH and the project is accessible. - Configure Claude Desktop to use this MCP server:
- On macOS, edit or create your user-level MCP configuration file at:
~/Library/Application Support/Claude/claude_desktop.json
. - Add the following server definition, replacing
/path/to/your/project/
with the absolute path to the directory where you cloned this project. You can refer to theclaude_desktop_config.json
file in this repository for an example.
- On macOS, edit or create your user-level MCP configuration file at:
The --directory
argument tells uv
where to find the homebrew_mcp.py
script and its context (like the .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
— Example configuration for Claude Desktop.mcp.json
— Example configuration for Cursor.requirements.txt
— Python project dependencies.
- Documentation & Metadata
README.md
— This file.LICENSE
— The project's MIT license..gitignore
— Specifies files for Git to ignore.
- Generated Files (Not in Git)
.venv/
— Python virtual environment managed byuv
.homebrew_mcp.log
— Log file for the MCP server.
Monitoring Logs
To watch the server log in real time and pretty-print each JSON line:
Tested Environment
This MCP server and its integration with Claude have been primarily tested on the following environment:
- macOS: Sonoma 14.7.5
- Homebrew: 4.5.8
- Python: 3.13 (managed via
uv
)- mcp module: 1.9.4 (installed using
uv pip
)
- mcp module: 1.9.4 (installed using
- anthropic module: 0.55.0 (installed using
uv pip
) - Claude Desktop: 0.10.38 (installed via Homebrew Cask on macOS).
- Cursor: 1.1.4
Example Prompts
Here are some example prompts you can use with Claude (or another MCP client) when interacting with this Homebrew MCP server:
- provide a summary of all installed packages
- check which packages are installed, and provide suggestions for other packages to install
- are there any problems with my homebrew setup? and how can I fix them ?
- show me information about the python 3.13 package
- install the wget package
Interactive Claude Test Script
To run the Claude integration test (test_claude_homebrew_mcp.py
), you need an Anthropic Claude API key. Set your API key in the ANTHROPIC_API_KEY
variable at the top of the test script. This script allows you to interact with Claude, which in turn uses the homebrew_mcp.py
server. It demonstrates dynamic tool discovery and Claude's ability to make multiple tool calls.
Example Test Run Output
This section shows an example of the output when running the test_claude_homebrew_mcp.py
script.
It demonstrates the interaction between Claude and the Homebrew MCP server, including dynamic tool discovery, multiple tool calls, and final responses.
License
MIT License
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
A Model Context Protocol server that enables interacting with the Homebrew package manager on macOS through natural language, supporting commands like install, search, info, and doctor.
Related MCP Servers
- -securityAlicense-qualityA Model Context Protocol server that integrates with Home Assistant to provide smart home control capabilities through natural language, supporting devices like lights, climate systems, locks, alarms, and humidifiers.Last updated -PythonMIT License
- -securityAlicense-qualityA Model Context Protocol server that allows large language models to control and query Home Assistant smart home systems through natural language interactions.Last updated -1TypeScriptMIT License
- AsecurityAlicenseAqualityA Model Context Protocol server that provides tools for Xcode-related operations, making it easier to work with iOS project management, building, testing, archiving, and deploying apps to both simulators and physical devices.Last updated -943JavaScriptMIT License
- -securityAlicense-qualityA Model Context Protocol (MCP) server that scrapes, indexes, and searches documentation for third-party software libraries and packages, supporting versioning and hybrid search.Last updated -231129TypeScriptMIT License