# homebrew-mcp

> Homebrew MCP Server — manage packages, casks, taps, and services through Claude on macOS.

[![PyPI version](https://img.shields.io/pypi/v/homebrew-mcp.svg)](https://pypi.org/project/homebrew-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue)](https://python.org)

> **macOS only** — requires [Homebrew](https://brew.sh) to be installed.

**19 tools** for searching, installing, upgrading, and managing Homebrew packages, casks, taps, and background services — all through natural language in Claude.

## Tools

### Search & Info (5)
| Tool | Description |
|------|-------------|
| `search` | Search for formulae or casks |
| `info` | Get detailed info about a package |
| `list_installed` | List all installed formulae or casks |
| `list_outdated` | List packages with newer versions available |
| `deps` | Show the dependency tree for a package |

### Package Management (5)
| Tool | Description |
|------|-------------|
| `install` | Install a formula or cask |
| `uninstall` | Uninstall a formula or cask |
| `upgrade` | Upgrade a specific package |
| `upgrade_all` | Upgrade all installed packages |
| `cleanup` | Remove old versions and stale downloads |

### Taps (3)
| Tool | Description |
|------|-------------|
| `tap` | Add a third-party repository (format: `user/repo`) |
| `untap` | Remove a third-party repository |
| `list_taps` | List all tapped repositories |

### Services (4)
| Tool | Description |
|------|-------------|
| `list_services` | List all managed background services and their status |
| `start_service` | Start a background service |
| `stop_service` | Stop a background service |
| `restart_service` | Restart a background service |

### System (2)
| Tool | Description |
|------|-------------|
| `doctor` | Run Homebrew diagnostics |
| `update` | Update Homebrew and formula definitions |

---

## Setup

### Requirements

- **macOS** with [Homebrew](https://brew.sh) installed
- Python 3.10+
- [uv](https://docs.astral.sh/uv/) package manager

### Install Homebrew (if needed)

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

### Install homebrew-mcp

```bash
pip install homebrew-mcp
# or with uv:
uv add homebrew-mcp
```

### Add to Claude Code

```bash
claude mcp add homebrew -- uvx homebrew-mcp
```

Or manually in your Claude config (`~/.claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "homebrew": {
      "command": "uvx",
      "args": ["homebrew-mcp"]
    }
  }
}
```

---

## Usage Examples

```
Install Docker Desktop:     install("docker", cask=True)
Install PostgreSQL:         install("postgresql")
Start PostgreSQL service:   start_service("postgresql")
List running services:      list_services()
Check for updates:          list_outdated()
Upgrade everything:         upgrade_all()
Add a tap:                  tap("homebrew/cask-fonts")
Run diagnostics:            doctor()
```

---

## Troubleshooting

**"brew: command not found":**
Install Homebrew first: [brew.sh](https://brew.sh)

**Permission errors during install:**
Some casks require admin password. Claude will show the brew output including any prompts.

**Service won't start:**
Check `doctor()` for system issues. Ensure the formula is installed first.

---

## Requirements

- macOS
- [Homebrew](https://brew.sh) installed
- Python 3.10+

## License

MIT — [Hitesh Gupta](https://github.com/dev-hitesh-gupta)
