Homebrew MCP Python Server

Homebrew MCP Python サーバー

macOS 上での Homebrew パッケージ管理のための Model Context Protocol（MCP）サーバーです。Claude Desktop やその他の MCP 互換クライアントとのシームレスな統合を目的として設計されています。

• 言語: Python 3.13
• MCP: Model Context Protocol
• パッケージマネージャー: Homebrew（macOS）
• Venv/依存関係マネージャー: uv

---

機能

• Homebrew コマンドを MCP ツールとして公開します。サポートされているコマンドは機能別にグループ化されています:
  • パッケージ管理: install、uninstall、upgrade、cleanup
  • 情報と検索: list、search、info、outdated、deps
  • システムヘルスとアップデート: doctor、update
  • Tap とソース管理: tap、untap
  • バージョン管理: pin、unpin
  • サービス管理: services
• subprocess 経由で実際の brew コマンドを実行します（macOS に Homebrew が必要です）。
• MCP 仕様に完全準拠しています（stdio、JSON-RPC 2.0、MCP 仕様 2025-06-18）。
• Claude Desktop やその他の LLM クライアント向けに設計されています。
• 関数型で宣言的な Python（クラスなし）。
• すべてのリクエスト/結果を homebrew_mcp.log にログ出力します。
• インタラクティブなテストスクリプト（test_claude_homebrew_mcp.py）が含まれており、以下のことを行います:
  • MCP サーバーから利用可能なツールを動的に取得します。
  • Claude が 1 つのユーザープロンプトに対して複数のツール呼び出しを行えるようにします。
  • 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 ファイルを確認することで、実行中であることを確認できます。

   Note: Claude Desktop と統合する場合、このコマンドを手動で実行する必要はありません。Claude Desktop は「Claude Desktop 統合」セクションで提供されている設定に基づいて、サーバーを自動的に起動します。このコマンドは直接テストまたは開発を目的としています。

---

Cursor 統合

前提条件: ツールを追加する前に、**インストール**セクションの手順を完了して、プロジェクトとその依存関係をセットアップしてください。「Add to Cursor」ボタンは、プロジェクトが ~/Documents/GitHub/homebrew-mcp に配置されていることを前提としています。

1. Cursor を Homebrew 経由でインストールします（macOS）:

   brew install --cask cursor
   

2. Cursor にツールを追加します:

   • 上記の「Add to 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. この MCP サーバーを使用するように Claude Desktop を設定します:

   • 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 License