Homebrew MCP Python Server

Homebrew MCP Python 服务

一个用于在 macOS 上管理 Homebrew 软件包的模型上下文协议（MCP）服务，旨在与 Claude Desktop 和其他兼容 MCP 的客户端无缝集成。

• 语言： Python 3.13
• MCP： 模型上下文协议
• 软件包管理器： Homebrew（macOS）
• 虚拟环境／依赖管理器： uv

---

功能

• 将 Homebrew 命令作为 MCP 工具提供。支持的命令按功能分组：
  • 软件包管理： install、uninstall、upgrade、cleanup
  • 信息与发现： list、search、info、outdated、deps
  • 系统健康与更新： doctor、update
  • Tap 与源管理： tap、untap
  • 版本管理： pin、unpin
  • 服务管理： services
• 通过子进程运行真实的 brew 命令（需要在 macOS 上安装 Homebrew）。
• 完全符合 MCP 规范（stdio、JSON-RPC 2.0、MCP 规范 2025-06-18）。
• 专为 Claude Desktop 和其他大模型客户端设计。
• 使用函数式、声明式 Python（无类）。
• 将所有请求／结果记录到 homebrew_mcp.log。
• 包含交互式测试脚本（test_claude_homebrew_mcp.py），该脚本：
  • 从 MCP 服务动态获取可用工具。
  • 允许 Claude 针对单个用户提示词调用多个工具。
  • 演示与 Anthropic API 的高级交互模式。

---

安装

1. 克隆此仓库：

   git clone https://github.com/jeannier/homebrew-mcp
   cd homebrew-mcp
   

2. 安装 uv（如果尚未安装）：

   brew install uv
   

3. 创建虚拟环境并安装依赖项：

   uv venv
   source .venv/bin/activate  # Activate the virtual environment
   uv pip install -r requirements.txt
   

4. 运行 MCP 服务（用于本地测试）： 若要在本地或开发期间测试服务，可以直接运行：

   uv run python homebrew_mcp.py
   

   随后服务将启动。如果成功，不会立即显示任何输出；它会通过 stdio 静默监听 MCP 请求。可通过检查 homebrew_mcp.log 文件确认服务正在运行。

   注意： 如果要与 Claude Desktop 集成，则无需手动运行此命令。Claude Desktop 会根据“Claude Desktop 集成”部分中提供的配置自动启动服务。此命令用于直接测试或开发。

---

Cursor 集成

前提条件： 添加工具之前，请完成 安装 部分中的步骤，以设置项目及其依赖项。“添加到 Cursor”按钮假定项目位于 ~/Documents/GitHub/homebrew-mcp。

1. 通过 Homebrew 安装 Cursor（macOS）：

   brew install --cask cursor
   

2. 将工具添加到 Cursor：

   • 点击上方的“添加到 Cursor”按钮。这将打开 Cursor 并自动安装工具。
   • 如果项目不在按钮假定的位置，则需要编辑生成的配置。在 macOS 上，此文件位于 ~/.cursor/mcp.json。打开文件，并更新 homebrew-mcp 条目中 command 字符串里的路径。可参考此仓库中的 mcp.json 文件。

3. 重启 Cursor：

   • 要启用工具，请在安装后重启 Cursor。

---

Claude Desktop 集成

1. 通过 Homebrew 安装 Claude Desktop（macOS）：

   brew install --cask claude
   

2. 确保 uv 位于 PATH 中，并且可以访问该项目。

3. 配置 Claude Desktop 以使用此 MCP 服务：

   • 在 macOS 上，编辑或创建用户级 MCP 配置文件：~/Library/Application Support/Claude/claude_desktop.json。
   • 添加以下服务定义，并将 /path/to/your/project/ 替换为克隆此项目所在目录的绝对路径。可参考此仓库中的 claude_desktop_config.json 文件。

{
  "mcpServers": {
    "homebrew-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/project/",
        "homebrew_mcp.py"
      ],
      "type": "stdio"
    }
  }
}

--directory 参数用于告知 uv 在哪里查找 homebrew_mcp.py 脚本及其上下文（例如 .venv）。

4. 重启 Claude Desktop。

---

项目结构

• Python 脚本
  • homebrew_mcp.py — MCP 服务主脚本。
  • test_claude_homebrew_mcp.py — Claude 交互集成测试脚本。
• 配置
  • claude_desktop_config.json — Claude Desktop 的示例配置。
  • mcp.json — Cursor 的示例配置。
  • requirements.txt — Python 项目依赖项。
• 文档与元数据
  • README.md — 本文件。
  • LICENSE — 项目的 MIT 许可证。
  • .gitignore — 指定 Git 忽略的文件。
• 生成的文件（不纳入 Git）
  • .venv/ — 由 uv 管理的 Python 虚拟环境。
  • homebrew_mcp.log — MCP 服务的日志文件。

---

监控日志

要实时查看服务日志并美化输出每一行 JSON：

tail -f homebrew_mcp.log | jq .

---

测试环境

此 MCP 服务及其与 Claude 的集成主要在以下环境中经过测试：

• macOS： Sonoma 14.7.5
• Homebrew： 4.5.8
• Python： 3.13（由 uv 管理）
  • mcp 模块： 1.9.4（使用 uv pip 安装）
• anthropic 模块： 0.55.0（使用 uv pip 安装）
• Claude Desktop： 0.10.38（在 macOS 上通过 Homebrew Cask 安装）。
• Cursor： 1.1.4

---

示例提示词

以下是使用此 Homebrew MCP 服务时，可向 Claude（或其他 MCP 客户端）发送的一些示例提示词：

• 汇总所有已安装的软件包
• 检查已安装的软件包，并建议还可以安装哪些软件包
• 我的 Homebrew 配置有问题吗？我该如何修复？
• 显示有关 python 3.13 软件包的信息
• 安装 wget 软件包

---

Claude 交互式测试脚本

要运行 Claude 集成测试（test_claude_homebrew_mcp.py），需要 Anthropic Claude API 密钥。请在测试脚本顶部的 ANTHROPIC_API_KEY 变量中设置 API 密钥。此脚本可让你与 Claude 交互，而 Claude 会使用 homebrew_mcp.py 服务。它展示了动态发现工具以及 Claude 执行多次工具调用的能力。

uv run python test_claude_homebrew_mcp.py

---

示例测试运行输出

本节展示运行 test_claude_homebrew_mcp.py 脚本时输出内容的示例。 它展示了 Claude 与 Homebrew MCP 服务之间的交互，包括动态发现工具、多次工具调用以及最终响应。

$ uv run python test_claude_homebrew_mcp.py

============================== Claude Prompt 1/7 ===============================
install wget if not installed, or uninstall if already installed
================================================================================
============================= Claude's Answer 1/7 ==============================
I'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.

Would you like me to proceed with uninstalling wget now? Please let me know.
================================================================================

============================== Claude Prompt 2/7 ===============================
restore initial state of wget
================================================================================
============================= Claude's Answer 2/7 ==============================
I've successfully uninstalled wget, returning your system to its initial state before our conversation. The wget package has been completely removed from your system.
================================================================================

============================== Claude Prompt 3/7 ===============================
check for outdated packages
================================================================================
============================= Claude's Answer 3/7 ==============================
You have 3 outdated packages:
1. libnghttp2
2. uv
3. yt-dlp

These packages have newer versions available and can be upgraded if you wish.
================================================================================

============================== Claude Prompt 4/7 ===============================
provide a summary of all installed packages
================================================================================
============================= Claude's Answer 4/7 ==============================
Here's a summary of all installed packages on your system:

1. **Command Line Tools & Utilities**: bash, coreutils, curl, git, jq, nmap, grep, watch, etc.
2. **Programming Languages & Tools**: python (multiple versions), node, go, lua
3. **Media Tools & Libraries**: ffmpeg and its dependencies (x264, x265, etc.), yt-dlp
4. **Development Tools**: neovim, tree-sitter, shellcheck
5. **Applications (Casks)**:
   - Browsers: google-chrome, firefox
   - Development: visual-studio-code, iterm2, cursor, github
   - Communication: discord, whatsapp
   - Media: vlc, spotify, stremio
   - Utilities: docker-desktop, keepassxc, alt-tab, disk-inventory-x
   - AI/ML tools: chatgpt, claude, ollama, superwhisper

You have 3 outdated packages (libnghttp2, uv, and yt-dlp) that could be updated.
================================================================================

============================== Claude Prompt 5/7 ===============================
provide 5 suggestions of other packages to install
================================================================================
============================= Claude's Answer 5/7 ==============================
Based on your installed packages and common developer tools, here are 5 suggested packages that would complement your setup:

1. **tmux** - A terminal multiplexer that allows you to manage multiple terminal sessions within a single window. Great companion to your iterm2 and neovim setup.

2. **htop** - An interactive process viewer and system monitor, much more feature-rich than the standard top command.

3. **ripgrep** - A faster alternative to grep, designed for searching code. Works well with your development tools.

4. **fzf** - A command-line fuzzy finder that can dramatically improve your terminal workflow for searching files, command history, and more.

5. **tldr** - Simplified and community-driven man pages with practical examples. Perfect for quickly finding common command usage patterns.

These 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?
================================================================================

============================== Claude Prompt 6/7 ===============================
use brew doctor to see if there are any issues, try to find a fix for all of these issues
================================================================================
============================= Claude's Answer 6/7 ==============================
Based on the complete analysis, here's my recommendation to fix the one minor warning:

Since 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.

If you want to fully resolve this warning, you have two options:

1. 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.

2. Keep both versions available and just be aware that you need to use the full name when referring to the tap version.

Since 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.

The brew doctor results suggest your Homebrew installation is actually in good shape with no critical issues that need fixing!
================================================================================

============================== Claude Prompt 7/7 ===============================
provide a summary of what was done
================================================================================
============================= Claude's Answer 7/7 ==============================
# Homebrew Session Summary

Here's a summary of what was done during our session:

1. **Checked and installed wget**:
   - Initially verified that wget was not installed on your system
   - Installed wget version 1.25.0

2. **Restored initial state**:
   - Uninstalled wget to return to the original system state

3. **Checked for outdated packages**:
   - Found 3 outdated packages: libnghttp2, uv, and yt-dlp

4. **Listed all installed packages**:
   - Displayed a complete list of installed formulae and casks
   - Your system has numerous development tools, utilities, and applications installed

5. **Suggested 5 additional packages**:
   - tmux: Terminal multiplexer
   - htop: Interactive process viewer
   - ripgrep: Fast alternative to grep
   - fzf: Command-line fuzzy finder
   - tldr: Simplified man pages

6. **Ran system diagnostics**:
   - Executed brew doctor to check for issues
   - Found only one minor warning related to the nextdns package having the same name in both core formulae and a custom tap
   - This warning is informational only and doesn't require action unless you experience issues with nextdns

7. **Examined package versions**:
   - Listed all installed packages with their versions to get a better understanding of your system configuration

Overall, your Homebrew installation appears to be in good health with only a minor naming conflict that doesn't impact functionality.
================================================================================

---

许可证

MIT 许可证