jeannier/homebrew-mcp

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
- 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
1. **Clone this repository:**
2. **Install uv (if not already):**
3. **Create a virtual environment and install dependencies:**
4. **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.
1. **Install Cursor via Homebrew (macOS):**
2. **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 the command string for the homebrew-mcp entry. The mcp.json file in this repository can be used as a reference.
3. **Restart Cursor**:
- For the tool to become active, restart Cursor after installation.
---
Claude Desktop Integration
1. **Install Claude Desktop via Homebrew (macOS):**
2. **Ensure uv is in your PATH and the project is accessible.**
3. **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.