Claude DesktopでBacklog MCPを使う。APIキーをファイルに書かずにmacOSのキーチェーンで渡す方法

Claude DesktopからBacklogの課題を見たり更新したりしたくて、Backlog MCPを入れてみました。

公式(Nulab)のREADMEには、設定ファイルに BACKLOG_API_KEY をそのまま書く例が載っています。ただ、APIキーを平文でJSONに置くのは気持ち悪いので、環境変数で渡せないかと考えたのがきっかけです。

結論から言うと、Claude Desktopでは環境変数を渡すのに少し回り道が必要でした。やったことをまとめます。

環境

最初にハマったところ

Claude Codeなら、.mcp.json に ${BACKLOG_API_KEY} と書いて、.zshrc に書いた環境変数を渡せます。

でもClaude Desktopは、次の2つの理由でこの方法が使えませんでした。

  • 設定ファイル(claude_desktop_config.json)の中で ${...} が展開されない
  • Dockなどから起動したアプリは .zshrc を読まないので、環境変数が渡らない

そこで、キーはmacOSのキーチェーンに入れておき、起動用のシェルスクリプトで取り出してBacklog MCPを起動する形にしました。

全体の流れ

  1. APIキーをキーチェーンに保存する
  2. キーチェーンからキーを取り出して起動するスクリプトを作る
  3. Claude Desktopの設定ファイルには、そのスクリプトのパスだけを書く

こうすると、設定ファイルにもスクリプトにもキー本体は残りません。

手順

1. BacklogでAPIキーを発行する

Backlogの「個人設定 → API」で発行します。あとで見て分かるように、メモは Backlog-Claude-Desktop-MCP のように用途が分かる名前にしました。

2. キーをキーチェーンに保存する

security add-generic-password -a "$USER" -s backlog-api-key -w

-w の後ろに何も書かないと、対話でキーの入力を求められます。コマンドにキーを直接書くと履歴に残るので、この形にしています。

保存できたかどうかは、キーチェーンアクセスで backlog-api-key を検索すると確認できます。

3. 起動用スクリプトを作る

~/bin/backlog-mcp.sh を作ります。

#!/bin/sh
export PATH="/Users/あなたのユーザー名/.nodebrew/current/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"
export BACKLOG_DOMAIN="your-domain.backlog.com"
export BACKLOG_API_KEY="$(security find-generic-password -s backlog-api-key -w)"
exec npx -y backlog-mcp-server

行っていることは次のとおりです。

  • 2行目: npx を見つけられるように PATH を通す
  • 3行目: 接続先のBacklogドメインを指定する
  • 4行目: キーチェーンからAPIキーを取り出して、環境変数に入れる
  • 5行目: Backlog MCPを起動する

~/bin を作って、実行権限を付けます。

mkdir -p ~/bin
chmod +x ~/bin/backlog-mcp.sh

PATH の1つ目は、which npx で出たフォルダに合わせてください。Desktopから起動したときは npx が見つからないことがあるので、ここは省略できません。

4. スクリプト単体で動くか確認する

~/bin/backlog-mcp.sh

エラーで終了せず、何も出ないまま待機状態になれば成功です。MCPサーバーは入力待ちで動き続けるので、プロンプトは戻ってきません。確認できたら Ctrl+C で止めます。

5. Claude Desktopの設定ファイルに追記する

「設定 → 開発者 → 構成を編集」から claude_desktop_config.json を開いて、mcpServers に追記します。

{
  "mcpServers": {
    "backlog": {
      "command": "/Users/あなたのユーザー名/bin/backlog-mcp.sh"
    }
  }
}

~ は使えないので、フルパスで書きます。すでに他のMCPがある場合は、mcpServers の中に "backlog": {...} だけを足します。カンマの付け忘れに注意です。

書式が合っているかは、次のコマンドで確認できます。

python3 -m json.tool "$HOME/Library/Application Support/Claude/claude_desktop_config.json" > /dev/null && echo OK

6. Claude Desktopを再起動する

ウィンドウを閉じるだけでは反映されないので、Cmd+Qで完全に終了してから起動し直します。

「設定 → 開発者」に backlog が出て、「実行中」になっていれば接続できています。

7. 動作確認

チャットで「WEBPJ2026 の課題一覧を出して」のように頼むと、Backlogのツールが呼ばれて、課題が返ってきます。プロジェクトキーや課題キーを入れて頼むと、Backlogのことだと判断してもらいやすいです。

初回は、ツールごとに許可の確認が出ます。課題の作成・更新・削除は別のツールなので、そのたびに確認が出ます。

つまずいたところ

キーチェーンアクセスを開いたら「パスワード」アプリに誘導される

新しいmacOSでは、Spotlightで「キーチェーン」と検索すると、「パスワード」アプリが先に出てきます。こちらには security コマンドで入れた項目が表示されません。

/System/Library/CoreServices/Applications/Keychain Access.app を直接開くと、「ログイン」キーチェーンの中に項目が見つかりました。

EBADENGINE の警告が出る

初回にスクリプトを実行したら、こんな警告が出ました。

npm warn EBADENGINE Unsupported engine {
  package: 'yargs@18.2.0',
  required: { node: '^20.19.0 || ^22.12.0 || >=23' },
  current: { node: 'v22.11.0', npm: '10.9.0' }
}

^20.19.0 || ^22.12.0 || >=23 は「20系なら20.19以上、22系なら22.12以上、23以上ならOK」という意味です。「20.19以上」ではなく、メジャーバージョンごとに下限が決まっています。v22.11.0 は22系なのに22.12に届いていないので、警告が出ていました。

動作はしていましたが、nodebrew use v22.12.0 で上げたら警告は消えました。nodebrew の current 経由でPATHを通しているので、スクリプトは書き換えずに済みました。

Chromeの拡張機能で操作するのとの違い

Claude in ChromeでもBacklogの画面は操作できます。ただ、MCPはAPIを直接呼ぶので、画面を開いて読み取る手間がなく、速いです。データを扱う作業(検索、一覧、コメントの読み書き)はMCPのほうが向いていて、APIにない操作だけChromeに任せる、という使い分けになりそうです。

まとめ

  • Claude Desktopは .zshrc を読まず、設定ファイルで環境変数も展開できないので、キーチェーン + 起動スクリプトで渡した
  • 設定ファイルにもスクリプトにも、APIキー本体は残らない
  • ハマりどころは、npx のPATHと、Nodeのバージョンの2点

最初の準備は少し面倒ですが、一度作ってしまえば、あとは普通にBacklogの課題を頼めるようになります。

コメント

タイトルとURLをコピーしました