Claude Backlog連携の設定方法とできること

Claude Backlog連携とは — 何ができるか

Claude Backlog連携とは、ヌーラボが開発するBacklog MCPサーバーをClaude Codeに接続し、Backlogの課題・プロジェクト・Wiki・Gitリポジトリを会話から操作できるようにする仕組みです。課題の一覧取得や新規作成、コメント追加、プルリクエストの確認を、Backlogの管理画面を開かずに頼めます。

機能は7つのツールセット(space / project / issue / wiki / git / notifications / document)に分かれ、既定では全部が有効です。「PROJECT-KEYプロジェクトに高優先度のバグ課題を作って」から「repo-nameのオープンなプルリクエストを一覧して」まで、1つの接続で頼めます。

このMCPサーバーはNulabが開発しMITライセンスで公開していますが、公式サポートや動作保証は付いていません。業務利用の前に、この位置づけを踏まえておくと導入判断がしやすくなります。

導入方法を選ぶ — Docker / npx / Node.jsの3通り

導入方法は3つあり、どれも最終的に同じMCPサーバーを起動します。

もっとも手間がかからないのはnpxです。事前にDockerを用意せず、claude mcp add一発で接続できます。

コマンドは「サーバー名を先頭に」書く

claude mcp add の --env は複数の値を受け取れる形式で、Claude Code v2.1.285のヘルプでは -e, --env <env...> と表示されます。--env を並べたあとにサーバー名を置くと、名前がもう1つの環境変数として読まれ、次のエラーで止まります。

claude mcp add --scope project --transport stdio \
  --env BACKLOG_DOMAIN=your-domain.backlog.com \
  --env BACKLOG_API_KEY=your-api-key \
  backlog -- npx backlog-mcp-server

Invalid environment variable format: backlog, environment variables should be added as: -e KEY1=value1 -e KEY2=value2

作業ディレクトリで実際に試した結果です(--scope project を付けてあり、.mcp.json は作られませんでした)。サーバー名を先に書くと、同じ内容が通ります。

claude mcp add backlog --transport stdio \
  --env BACKLOG_DOMAIN=your-domain.backlog.com \
  --env BACKLOG_API_KEY=your-api-key \
  -- npx backlog-mcp-server

Dockerで動かす場合も、名前を先頭に置く形は同じです。イメージは ghcr.io/nulab/backlog-mcp-server として公開されています。

claude mcp add backlog --transport stdio \
  --env BACKLOG_DOMAIN=your-domain.backlog.com \
  --env BACKLOG_API_KEY=your-api-key \
  -- docker run --pull always -i --rm \
  -e BACKLOG_DOMAIN -e BACKLOG_API_KEY \
  ghcr.io/nulab/backlog-mcp-server

BACKLOG_DOMAIN には接続先のドメイン(your-domain.backlog.com)、BACKLOG_API_KEY にはBacklog側で発行したAPIキーを指定します。認証方式はAPIキーとOAuth 2.0の2種類で、Backlogの認証ドキュメントによればAPIキーはクエリパラメーター apiKey かヘッダー Backlog-API-Key で送られます。

ツールセットを絞って権限とコンテキストを制御する

READMEは --enable-toolsets をコンテキスト削減の手段として挙げています。Claude Codeは既定のツール検索で、ツール定義の読み込みを必要になるまで遅らせるため、影響は小さめです。ツール検索を使わない構成(ENABLE_TOOL_SEARCH=false やカスタム ANTHROPIC_BASE_URL)では効きます。絞る主な目的は、Claudeが呼べる操作の範囲を狭めることです。環境変数 ENABLE_TOOLSETS でも同じ指定ができます。

コードレビュー用途に絞るなら --enable-toolsets git,issue で十分です。ただしREADMEは、他のツールがプロジェクト情報を入口にするため project を残すことを勧めています。読み取り専用の利用に留めたいときは、Claude Code側の権限設定で書き込み系ツールを個別に止める方法もあります。

MCPサーバーが公開していない操作

削除系のツールは delete_issue delete_version delete_watching の3つだけです。READMEの一覧では delete_version が delete_version_milestone と書かれていますが、実際のツール名は delete_version なので、権限ルールには実際のツール名を使います。Backlog本体のAPIにはプロジェクトの削除やWikiページの削除がありますが、MCPサーバー側には対応するツールがありません。課題コメントも、取得・追加・更新はできても削除のツールは見当たりません。

つまり「プロジェクトを消して」と頼んでも、Claudeが呼べるツールがないため実行されません。誤操作の心配が減る一方で、これらの操作は今もBacklogの画面から行う必要があります。ツール名は操作ごとに分かれているので、get_issue は許可して add_issue は確認を求める、といった細かい制御もできます。

同じMCP経由の連携でも、操作を1つのツールにまとめる設計のサービスでは、この粒度の制御ができないことがあります。kickflowのMCPサーバーがその例で、読み取りと書き込みが同じツール名を通るため、ツール単位の許可では操作の種類を区別できません。

ツールの説明文を社内ルールに合わせて上書きする

複数のMCPサーバーを同時に運用していると、ツールの説明文が似通っていて、Claudeがどちらを呼ぶか迷うことがあります。Backlog MCPサーバーは、ホームディレクトリの .backlog-mcp-serverrc.json でツールの説明文を上書きできます。READMEによれば、これは出力言語を変える機能ではなく、ツールの選び方や引数の埋め方を誘導するための仕組みです。

{
  "TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "コメントには必ず課題キーを先頭に書くこと"
}

上書きの優先順位は、環境変数(BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION のように接頭辞 BACKLOG_MCP_ を付けた名前)、設定ファイル、組み込みの既定値の順です。設定ファイルはサーバー起動時に読み込まれるため、変更したらサーバーを再起動します。

Dockerで動かす場合、ホームディレクトリの指すのはコンテナの中です。READMEの例では -v /yourcurrentdir/.backlog-mcp-serverrc.json:/root/.backlog-mcp-serverrc.json:ro のようにファイルをマウントしています。キー名は --export-descriptions を付けて起動すると一覧で確認できます。

大きな一覧が返らないとき — 2つの上限を見る

課題の一覧のように大きな結果は、Backlog MCPサーバーとClaude Codeの両方で長さに上限があります。挙動は異なり、Backlog側は超えた分を切り詰め、Claude Code側は結果をファイルに退避します。

Backlog側の50,000より、Claude Code側の既定25,000のほうが小さい点に注意が要ります。Backlogの MAX_TOKENS だけを上げても、Claude Code側の上限が先に効く可能性があります。

Claude Codeは25,000トークンを超えた結果をファイルに退避し、会話にはそのパスだけを残します。Claudeは必要になったときにそのファイルを読みます。一覧が本当に途中で切れているなら、Backlog側の MAX_TOKENS が原因です。退避が起きているなら MAX_MCP_OUTPUT_TOKENS を確認します。

上限を上げる以外に、--optimize-response で一覧系のツールに fields 引数を加える方法があります。get_project_list(fields: ["id", "projectKey", "name"]) のように必要な項目だけを頼めます。一覧を返すツールだけが対象で、1件を返すツールには付きません。選べるのはトップレベルの項目のみで、入れ子のオブジェクトは丸ごと返ります。

公式サポートなしという条件をどう扱うか

前述のとおり、このMCPサーバーは無保証・無公式サポートという条件で公開されています。個人利用であれば大きな問題にはなりませんが、業務の中核フローに組み込むなら、運用面の判断がもう一段必要です。

現実的な対応は3つあります。更新のたびに動作確認をしてから導入する。バージョンを固定して意図しない自動更新を避ける。障害時にBacklogの画面から直接操作できる経路を残す。GitHubのIssueを事前に眺めておくと、既知の不具合を把握したうえで判断できます。

これはBacklog MCPサーバーに限らず、有志が保守するMCPサーバー全般に共通する前提です。公式ベンダーが直接メンテナンスするコネクタとは、障害時に頼れる窓口の有無が違います。

チームで共有する・複数組織にまたがる場合

チーム全員が同じBacklog接続を使いたいときは、--scope project で .mcp.json に設定を残します。リポジトリを開いたメンバーは、ワークスペースを信頼して承認すると同じ接続を使えます。承認するまでは、サーバーは承認待ちのままです。

ここで注意が必要です。実機で --scope project を付け、サーバー名を先頭にした成功形を実行すると、.mcp.json が作られ、--env に渡したAPIキーが平文のまま書かれます。確認した出力は次のとおりです(値は例示用のダミー)。

{
  "mcpServers": {
    "backlog": {
      "type": "stdio",
      "command": "npx",
      "args": ["backlog-mcp-server"],
      "env": {
        "BACKLOG_DOMAIN": "your-domain.backlog.com",
        "BACKLOG_API_KEY": "your-api-key"
      }
    }
  }
}

このファイルをそのままリポジトリにコミットすると、キーが共有されます。Claude Codeは .mcp.json の env で ${VAR} 形式の環境変数展開に対応しているので、"BACKLOG_API_KEY": "${BACKLOG_API_KEY}" と書き換えれば、各メンバーが自分のキーをシェルの環境変数に置く運用にできます。未設定の変数は警告として claude mcp list に出ます。

複数のBacklogスペースを横断するときは、組織ごとに BACKLOG_ORG_<NAME>_DOMAIN と BACKLOG_ORG_<NAME>_API_KEY を設定し、BACKLOG_DEFAULT_ORG で既定の組織を指定します。この構成ではツールに organization 引数が加わり、指定した組織へ処理が振り分けられます。BACKLOG_DEFAULT_ORG を欠くと、サーバーは起動時に失敗します。組織名の一覧は list_organizations ツールで取得できます。

単一組織のときは organization 引数が公開されず、READMEによればツール定義の約8KB分が節約されます。

ネットワーク越しに公開する(HTTP+OAuth)

--transport http でStreamable HTTPに切り替え、OAuth 2.0認証を有効にする構成もあります。利用者ごとに自分のBacklogアカウントで認証するため、APIキーをチームで使い回さずに済みます。

HTTPで公開するときの既定のバインド先は 127.0.0.1 です。他の端末から使うなら --http-host 0.0.0.0 でバインド先を変えます。0.0.0.0 で待ち受けるなら --http-allowed-hosts に公開ホスト名を指定するのが実質必須で、指定しないとDNSリバインディング対策が働かず、起動時に警告が出ます。リバースプロキシの背後に置くときも同様で、同じ端末のプロキシ経由なら、バインドは 127.0.0.1 のまま --http-allowed-hosts だけで足ります。OAuthの仕組みはリモートMCPのOAuth認証で扱っています。

よくあるつまずき

• コマンドを実行すると Invalid environment variable format と出る: サーバー名が --env の後ろにあります。名前を claude mcp add の直後に移します
• claude mcp list で接続に失敗する: BACKLOG_DOMAIN の書式を確認します。READMEの例は your-domain.backlog.com のようにドメインだけで、https:// を付ける例はありません
• 一覧取得の結果が途中で切れる、または返らない: 上の2つの上限を確認します。--optimize-response で必要な項目だけに絞る手もあります
• 他のMCPサーバーとツール名が衝突する: --prefix backlog_ を付けると、get_project が backlog_get_project のように名前空間が分かれ、衝突を避けられます
• 接続はできるがツールが呼ばれない: 権限設定で該当ツールが deny になっていないか、/permissions で確認します。切り分けの手順はMCPサーバーに接続できないときの切り分け手順にまとめています
• Dockerで --pull always が使えない環境がある: 毎回のpullができないときは、docker pull ghcr.io/nulab/backlog-mcp-server:latest を手動で実行し、--pull always を外した設定に切り替えます
• HTTPに切り替えたら他の端末から届かない: 既定のバインド先は 127.0.0.1 です。--http-host 0.0.0.0 でバインド先を変え、あわせて --http-allowed-hosts に公開ホスト名を指定します

まとめ

導入は3通りありますが、詰まりやすいのは--envとサーバー名の順序と、.mcp.json へのAPIキーの平文保存です。共有する前にこの2点を確かめておくと、権限やツールの絞り込みを設計する段階へ進めます。