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 - Exposes Homebrew commands as MCP tools. The supported commands are grouped by function: - Package Management:
Add this skill
npx mdskills install jeannier/homebrew-mcpWell-documented MCP server exposing comprehensive Homebrew tools with excellent setup instructions and examples
1# Homebrew MCP Python Server23A Model Context Protocol (MCP) server for Homebrew package management **on macOS**, designed for seamless integration with Claude Desktop and other MCP-compatible clients.45- **Language:** Python 3.136- **MCP:** [Model Context Protocol](https://github.com/modelcontextprotocol/python-sdk)7- **Package Manager:** Homebrew (macOS)8- **Venv/Dependency Manager:** [uv](https://github.com/astral-sh/uv)910---1112## Features1314- Exposes Homebrew commands as MCP tools. The supported commands are grouped by function:15 - **Package Management:** `install`, `uninstall`, `upgrade`, `cleanup`16 - **Information & Discovery:** `list`, `search`, `info`, `outdated`, `deps`17 - **System Health & Updates:** `doctor`, `update`18 - **Tap & Source Management:** `tap`, `untap`19 - **Version Management:** `pin`, `unpin`20 - **Service Management:** `services`21- Runs real `brew` commands via subprocess (requires Homebrew on macOS).22- Fully MCP spec-compliant (stdio, JSON-RPC 2.0, MCP spec 2025-06-18).23- Designed for Claude Desktop and other LLM clients.24- Functional, declarative Python (no classes).25- Logs all requests/results to `homebrew_mcp.log`.26- Includes an interactive test script (`test_claude_homebrew_mcp.py`) that:27 - Dynamically fetches available tools from the MCP server.28 - Allows Claude to make multiple tool calls for a single user prompt.29 - Demonstrates advanced interaction patterns with the Anthropic API.3031---3233## Installation34351. **Clone this repository:**36 ```sh37 git clone https://github.com/jeannier/homebrew-mcp38 cd homebrew-mcp39 ```402. **Install [uv](https://github.com/astral-sh/uv) (if not already):**41 ```sh42 brew install uv43 ```443. **Create a virtual environment and install dependencies:**45 ```sh46 uv venv47 source .venv/bin/activate # Activate the virtual environment48 uv pip install -r requirements.txt49 ```504. **Run the MCP Server (for Local Testing):**51 To test the server locally or during development, you can run it directly:52 ```sh53 uv run python homebrew_mcp.py54 ```55 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.5657 > **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.5859---6061## Cursor Integration6263**Prerequisite:** Before adding the tool, please complete the steps in the **[Installation](#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`.6465<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=homebrew-mcp&config=eyJjb21tYW5kIjoidXYgcnVuIC0tZGlyZWN0b3J5IH4vRG9jdW1lbnRzL0dpdEh1Yi9ob21lYnJldy1tY3AgaG9tZWJyZXdfbWNwLnB5In0=">66 <img src="https://img.shields.io/badge/add%20to-cursor-4285f4" alt="Add to Cursor">67</a>68691. **Install Cursor via Homebrew (macOS):**70 ```sh71 brew install --cask cursor72 ```73742. **Add the Tool to Cursor**:75 - Click the "Add to Cursor" button above. This will open Cursor and automatically install the tool.76 - 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 the `command` string for the `homebrew-mcp` entry. The `mcp.json` file in this repository can be used as a reference.77783. **Restart Cursor**:79 - For the tool to become active, restart Cursor after installation.8081---8283## Claude Desktop Integration84851. **Install Claude Desktop via Homebrew (macOS):**86 ```sh87 brew install --cask claude88 ```89902. **Ensure `uv` is in your PATH and the project is accessible.**91923. **Configure Claude Desktop to use this MCP server:**93 - On macOS, edit or create your user-level MCP configuration file at: `~/Library/Application Support/Claude/claude_desktop.json`.94 - 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 the `claude_desktop_config.json` file in this repository for an example.9596```json97{98 "mcpServers": {99 "homebrew-mcp": {100 "command": "uv",101 "args": [102 "run",103 "--directory",104 "/path/to/your/project/",105 "homebrew_mcp.py"106 ],107 "type": "stdio"108 }109 }110}111```112 *The `--directory` argument tells `uv` where to find the `homebrew_mcp.py` script and its context (like the `.venv`).*1131144. **Restart Claude Desktop.**115116---117118## Project Structure119120- **Python Scripts**121 - `homebrew_mcp.py` — Main MCP server script.122 - `test_claude_homebrew_mcp.py` — Interactive Claude integration test script.123- **Configuration**124 - `claude_desktop_config.json` — Example configuration for Claude Desktop.125 - `mcp.json` — Example configuration for Cursor.126 - `requirements.txt` — Python project dependencies.127- **Documentation & Metadata**128 - `README.md` — This file.129 - `LICENSE` — The project's MIT license.130 - `.gitignore` — Specifies files for Git to ignore.131- **Generated Files (Not in Git)**132 - `.venv/` — Python virtual environment managed by `uv`.133 - `homebrew_mcp.log` — Log file for the MCP server.134135---136137## Monitoring Logs138139To watch the server log in real time and pretty-print each JSON line:140141```sh142tail -f homebrew_mcp.log | jq .143```144145---146147## Tested Environment148149This MCP server and its integration with Claude have been primarily tested on the following environment:150151- **macOS:** Sonoma 14.7.5152- **Homebrew:** 4.5.8153- **Python:** 3.13 (managed via `uv`)154 - **mcp module:** 1.9.4 (installed using `uv pip`)155- **anthropic module:** 0.55.0 (installed using `uv pip`)156- **Claude Desktop:** 0.10.38 (installed via Homebrew Cask on macOS).157- **Cursor:** 1.1.4158159---160161## Example Prompts162163Here are some example prompts you can use with Claude (or another MCP client) when interacting with this Homebrew MCP server:164165- provide a summary of all installed packages166- check which packages are installed, and provide suggestions for other packages to install167- are there any problems with my homebrew setup? and how can I fix them ?168- show me information about the python 3.13 package169- install the wget package170171---172173## Interactive Claude Test Script174175To 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.176177```sh178uv run python test_claude_homebrew_mcp.py179```180181---182183## Example Test Run Output184185This section shows an example of the output when running the `test_claude_homebrew_mcp.py` script.186It demonstrates the interaction between Claude and the Homebrew MCP server, including dynamic tool discovery, multiple tool calls, and final responses.187188```189$ uv run python test_claude_homebrew_mcp.py190191============================== Claude Prompt 1/7 ===============================192install wget if not installed, or uninstall if already installed193================================================================================194============================= Claude's Answer 1/7 ==============================195I've successfully installed wget on your system. Now that wget is installed, if you'd like me to uninstall it instead (as per your request to either install if not present or uninstall if already installed), I can do that for you.196197Would you like me to proceed with uninstalling wget now? Please let me know.198================================================================================199200============================== Claude Prompt 2/7 ===============================201restore initial state of wget202================================================================================203============================= Claude's Answer 2/7 ==============================204I've successfully uninstalled wget, returning your system to its initial state before our conversation. The wget package has been completely removed from your system.205================================================================================206207============================== Claude Prompt 3/7 ===============================208check for outdated packages209================================================================================210============================= Claude's Answer 3/7 ==============================211You have 3 outdated packages:2121. libnghttp22132. uv2143. yt-dlp215216These packages have newer versions available and can be upgraded if you wish.217================================================================================218219============================== Claude Prompt 4/7 ===============================220provide a summary of all installed packages221================================================================================222============================= Claude's Answer 4/7 ==============================223Here's a summary of all installed packages on your system:2242251. **Command Line Tools & Utilities**: bash, coreutils, curl, git, jq, nmap, grep, watch, etc.2262. **Programming Languages & Tools**: python (multiple versions), node, go, lua2273. **Media Tools & Libraries**: ffmpeg and its dependencies (x264, x265, etc.), yt-dlp2284. **Development Tools**: neovim, tree-sitter, shellcheck2295. **Applications (Casks)**:230 - Browsers: google-chrome, firefox231 - Development: visual-studio-code, iterm2, cursor, github232 - Communication: discord, whatsapp233 - Media: vlc, spotify, stremio234 - Utilities: docker-desktop, keepassxc, alt-tab, disk-inventory-x235 - AI/ML tools: chatgpt, claude, ollama, superwhisper236237You have 3 outdated packages (libnghttp2, uv, and yt-dlp) that could be updated.238================================================================================239240============================== Claude Prompt 5/7 ===============================241provide 5 suggestions of other packages to install242================================================================================243============================= Claude's Answer 5/7 ==============================244Based on your installed packages and common developer tools, here are 5 suggested packages that would complement your setup:2452461. **tmux** - A terminal multiplexer that allows you to manage multiple terminal sessions within a single window. Great companion to your iterm2 and neovim setup.2472482. **htop** - An interactive process viewer and system monitor, much more feature-rich than the standard top command.2492503. **ripgrep** - A faster alternative to grep, designed for searching code. Works well with your development tools.2512524. **fzf** - A command-line fuzzy finder that can dramatically improve your terminal workflow for searching files, command history, and more.2532545. **tldr** - Simplified and community-driven man pages with practical examples. Perfect for quickly finding common command usage patterns.255256These tools would enhance your command-line productivity and integrate well with your existing development environment. Would you like more information about any of these packages?257================================================================================258259============================== Claude Prompt 6/7 ===============================260use brew doctor to see if there are any issues, try to find a fix for all of these issues261================================================================================262============================= Claude's Answer 6/7 ==============================263Based on the complete analysis, here's my recommendation to fix the one minor warning:264265Since this is just a warning about having both the core and tap version of nextdns available, and you're actually using the core version (as shown by the info command), this isn't causing any functional problems with your system. The warning is simply informing you that if you want to specifically use the tap version, you need to use the full name.266267If you want to fully resolve this warning, you have two options:2682691. Continue using the core version of nextdns (which you are currently using) and untap the nextdns tap to remove the ambiguity. This would require identifying the exact tap name and then using the untap command.2702712. Keep both versions available and just be aware that you need to use the full name when referring to the tap version.272273Since the warning isn't causing any actual issues with your Homebrew installation and everything is functioning correctly, I would recommend option 2 - simply being aware of the naming convention when you need to use the tap version.274275The brew doctor results suggest your Homebrew installation is actually in good shape with no critical issues that need fixing!276================================================================================277278============================== Claude Prompt 7/7 ===============================279provide a summary of what was done280================================================================================281============================= Claude's Answer 7/7 ==============================282# Homebrew Session Summary283284Here's a summary of what was done during our session:2852861. **Checked and installed wget**:287 - Initially verified that wget was not installed on your system288 - Installed wget version 1.25.02892902. **Restored initial state**:291 - Uninstalled wget to return to the original system state2922933. **Checked for outdated packages**:294 - Found 3 outdated packages: libnghttp2, uv, and yt-dlp2952964. **Listed all installed packages**:297 - Displayed a complete list of installed formulae and casks298 - Your system has numerous development tools, utilities, and applications installed2993005. **Suggested 5 additional packages**:301 - tmux: Terminal multiplexer302 - htop: Interactive process viewer303 - ripgrep: Fast alternative to grep304 - fzf: Command-line fuzzy finder305 - tldr: Simplified man pages3063076. **Ran system diagnostics**:308 - Executed brew doctor to check for issues309 - Found only one minor warning related to the nextdns package having the same name in both core formulae and a custom tap310 - This warning is informational only and doesn't require action unless you experience issues with nextdns3113127. **Examined package versions**:313 - Listed all installed packages with their versions to get a better understanding of your system configuration314315Overall, your Homebrew installation appears to be in good health with only a minor naming conflict that doesn't impact functionality.316================================================================================317```318319---320321## License322323MIT License324
Full transparency — inspect the skill content before installing.