Backlog MCPサーバーは、BacklogのAPIをClaude CodeやCodex、Claude DesktopなどのAIクライアントから呼べるようにする、ヌーラボ公開のMCPサーバーです。課題の検索や起票、Wikiやドキュメントの参照、プルリクエストへのコメントまでAIに任せられます。この記事では、2026年10月23日公開の0.23.2を手元で起動して数えた64ツールの内訳をもとに、登録コマンドの正しい書き方、ツールセットの絞り込み、削除系を止める権限設定、応答の切り詰めとレート制限の落とし穴を確認します。
まとめ：Backlog MCPで最初に決めるAPIキーの主体と有効にするツールセット
Node.jsなどの実行環境を準備したら、APIキーを発行し、BACKLOG_DOMAIN と BACKLOG_API_KEY を渡して npx -y backlog-mcp-server を起動する設定を1つ足すだけです。
先に決めるべきは2点です。1つ目は誰のAPIキーで動かすか。APIキーには操作範囲を絞る設定が無く、発行したユーザーの権限がそのままAIの操作範囲になります。2つ目はどのツールを使わせるか。ENABLE_TOOLSETS はツールセット単位で、課題を読むために issue を有効にすると delete_issue も読み込まれます。0.20.6で全ツールに読み取り専用かどうかを示すヒントが付きましたが、Claude Codeはこのヒントで確認を省きません。削除系は permissions.deny で止め、応答の上限は MAX_TOKENS=10000 程度に下げる。この3つを最初の設定に含めてください。
Backlog MCPサーバーの提供元と0.23系の64ツール構成
MCPそのものの仕組みはMCPの仕組みとMCPサーバーの作り方で解説しています。ここではBacklog版の成り立ちとツールの中身を押さえます。
ヌーラボ公開のMIT版とサポート窓口の対象外になる運用上の意味
公式実装はnulab/backlog-mcp-serverで、TypeScript製のMITライセンスです。npmの登録情報では最初の版が2025年3月7日に出ており、2026年10月27日時点の最新は10月23日公開の0.23.2です。package.json の動作要件はNode.js 22以上で、Docker版のイメージは node:26-slim を土台にしています。
注意したいのはサポートの扱いです。Backlogヘルプセンターの案内は、MITライセンスで提供しており、ヌーラボのサポート窓口では公式サポートを提供していないと明記しています。不具合の報告先はGitHubのIssuesです。Backlog本体の契約サポートを前提に社内展開の稟議を書くと、ここで話が食い違います。
7ツールセットのツール数と読み取り・破壊的の内訳
0.23.2をダミーのAPIキーで起動し、tools/list の結果を数えました（一覧の取得だけならBacklogへの通信は起きません）。読み取りと破壊的は各ツールの readOnlyHint・destructiveHint の集計です。
| ツールセット | ツール数 | 読み取り | 破壊的 | 主な操作 |
|---|---|---|---|---|
| space | 6 | 6 | 0 | スペース・ユーザー・自分の情報 |
| project | 5 | 3 | 1 | プロジェクトの一覧・追加・更新 |
| issue | 29 | 14 | 8 | 課題・コメント・マイルストーン |
| wiki | 5 | 3 | 1 | Wikiの取得・追加・更新 |
| git | 10 | 6 | 2 | リポジトリ・プルリクエスト |
| document | 5 | 4 | 0 | 文書ツリー・本文・コメント・追加 |
| notifications | 4 | 2 | 0 | 通知の取得・既読化 |
| 合計 | 64 | 38 | 12 | 残り14は追加・既読化 |
ツール名は get_issues・add_pull_request_comment のように操作と対象を並べた形です。中心は issue の29個で、複数スペースを設定したときだけ list_organizations が加わります。
0.20.6から0.23.2までの2026年10月の設定関連変更
検索上位の記事にあるツール数36・47・63は、執筆時点の版の違いです。リリース一覧から設定に響く変更を拾います。
- 0.20.6（2026年10月8日）：PR #267で全ツールに
readOnlyHint・destructiveHintなどのヒントを付与 - 0.21.0（10月13日）：PR #270で応答を返す前に圧縮する処理を常時有効化（破壊的変更）
- 0.21.1（10月13日）：ドキュメントのコメントを取る
get_document_commentsを追加し64ツールに - 0.22.0（10月13日）：PR #274で
get_documentがプレーンテキストだけを返すように変わり、startとlimitで分割して読めるように - 0.23.0（10月21日）：PR #282で入れ子のプロジェクト・課題と表示用の項目も圧縮対象に
圧縮では、入れ子のユーザーが id・userId・name の3項目に縮み、空の項目は省かれます。担当者のメールアドレスなどを読む前提の指示文は、更新後に項目が消えています。業務では [email protected] のように版を固定し、リリース一覧を読んでから上げてください。
Claude Code・Codex・Claude DesktopにBacklog MCPを登録する手順
Claude Code自体の初期設定はClaude Codeの使い方と権限設定にまとめています。
個人設定のAPIから発行するAPIキーとBACKLOG_DOMAINの書式
APIキーはBacklogヘルプの「APIの設定」のとおり、個人設定のAPI画面で発行します。入力できるのはメモ欄だけで、読み取り専用にする、特定プロジェクトに限る、といった項目はありません。
BACKLOG_DOMAIN には https:// を付けないホスト名（your-space.backlog.com か your-space.backlog.jp）を入れます。アドレス欄から写したときは先頭のスキームを消してください。
claude mcp addのenvオプションとサーバー名の配置
Claude Code 2.1.302で、--transport stdio を先に書き、--env を2つ並べた直後に backlog を置く書き方を試すと、「Invalid environment variable format: backlog」で止まりました。Claude CodeのMCP接続ドキュメントも、--env は複数の KEY=value を受け取るため、直後のサーバー名を値として読んでしまうと説明しています。--env とサーバー名のあいだに別のオプションを挟めば通ります。
claude mcp add \
--env BACKLOG_DOMAIN=your-space.backlog.com \
--env BACKLOG_API_KEY=your-api-key \
--transport stdio --scope project \
backlog -- npx -y [email protected]--scope project を付けるとカレントディレクトリに .mcp.json が作られます。/mcp でbacklogがconnectedになり、「自分のBacklogユーザー情報を取得して」と頼んで get_myself が呼ばれれば、APIキーまで通っています。
.mcp.jsonでチーム共有しAPIキーを環境変数展開で外に出す設定
上のコマンドで作られる .mcp.json にはAPIキーが平文で入ります。リポジトリに入れるなら、${VAR} の環境変数展開に書き換えて各自の値を読ませます。
{
"mcpServers": {
"backlog": {
"type": "stdio",
"command": "npx",
"args": ["-y", "[email protected]"],
"env": {
"BACKLOG_DOMAIN": "your-space.backlog.com",
"BACKLOG_API_KEY": "${BACKLOG_API_KEY}",
"ENABLE_TOOLSETS": "space,project,issue,wiki",
"MAX_TOKENS": "10000"
}
}
}
}各自はシェルの設定などで BACKLOG_API_KEY を定義しておくだけです。Dockerで動かす場合は、READMEの例どおり command を docker にし、run --pull always -i --rm -e BACKLOG_DOMAIN -e BACKLOG_API_KEY -e ENABLE_TOOLSETS -e MAX_TOKENS ghcr.io/nulab/backlog-mcp-server を引数に並べます。Node.jsの版を揃えにくいチームではDocker版が手戻りを減らします。
Codexのconfig.tomlによる環境変数の引き継ぎと書き込み承認設定
Codex CLI 0.164.0では codex mcp add backlog --env BACKLOG_DOMAIN=… --env BACKLOG_API_KEY=… -- npx -y backlog-mcp-server の順で登録でき、~/.codex/config.toml にAPIキーが平文で書かれました。CodexのMCPドキュメントにある env_vars を使えば、キーを設定ファイルに残さずシェルの環境変数から渡せます。
[mcp_servers.backlog]
command = "npx"
args = ["-y", "[email protected]"]
env_vars = ["BACKLOG_API_KEY"]
default_tools_approval_mode = "writes"
disabled_tools = ["delete_issue", "delete_version", "delete_watching", "remove_related_issue"]
[mcp_servers.backlog.env]
BACKLOG_DOMAIN = "your-space.backlog.com"
ENABLE_TOOLSETS = "space,project,issue,wiki"
MAX_TOKENS = "10000"default_tools_approval_mode = "writes" は、読み取り専用の印が無いツールだけ確認を求める設定で、0.20.6のヒント追加から意図どおりに働きます。disabled_tools の4つは読み込まれません。
Claude Desktopの拡張機能で入れる場合に指定できる項目
Claude Desktopの拡張機能の画面から入れる方法もあります。リポジトリ同梱の拡張機能定義 manifest.json では、入力項目はAPIキーとドメインの2つだけで、ENABLE_TOOLSETS や MAX_TOKENS を渡す欄はありません。この経路では、インストールされた拡張機能に含まれる版の全ツールセットが既定で有効になります。同じファイルの version 欄は2026年10月27日時点で0.11.1のままなので、接続後にツール一覧で数と名前を確かめてください。絞りたい場合は claude_desktop_config.json の mcpServers に上と同じ command・args・env を設定し、APIキーはClaude Desktopの起動環境で利用できる方法で渡します。
ENABLE_TOOLSETSとMAX_TOKENSで応答量とツール数を絞る設定
Claude Codeは既定でツール検索を使い、起動時に読み込むのはツール名とサーバーの説明だけです。それでも名前の一覧は毎回載り、検索で引いた定義も文脈に入ります。0.23.2の tools/list が返すツール定義は約5.1万文字（JSONを区切りの空白付きで書き出して数えた値）でした。使わないツールを外すと、選び間違いと文脈の消費がともに減ります。
用途別に有効化するツールセットの組み合わせと読み込まれるツール数
ENABLE_TOOLSETS の既定値は all で、カンマ区切りで指定したツールセットだけが読み込まれます。READMEは、ほかのツールの入口になる project を有効にしておくよう勧めています。0.23.2で組み合わせごとに数えた結果です。
- 課題の確認と起票だけ：
space,project,issue（40ツール・うち破壊的9） - 仕様をWikiから読んで実装する：
space,project,issue,wiki（45ツール・同10） - Wikiに加えてドキュメントも読む：
space,project,issue,wiki,document（50ツール・同10） - プルリクエストのレビュー補助：
space,project,git（21ツール・同3）
notifications はまず外してかまいません。別のMCPサーバーとツール名が重なるときは、PREFIX=backlog_ で backlog_get_issues のような名前に変えられます。GitHub MCPサーバーのtoolset設計と並べると、どちらもプルリクエスト系の取得ツールを持つため、両方入れる環境では付けておくと安全です。
MAX_TOKENSの既定値とClaude Codeの出力制限の違い
Backlog MCPサーバーは応答が MAX_TOKENS（既定50,000）を超えると、wrapWithTokenLimit.ts の処理で、JSON文字列の先頭から MAX_TOKENS の4倍の文字数で切り、末尾に切り詰めの注記を付けます。数え方は英単語のかたまりと記号・和文の1文字ずつを1と数える簡易なものです。
和文の課題300件を模した応答を同じ処理に通すと、MAX_TOKENS=20000 では切り詰め後も80,041文字、12500で50,041文字、10000で40,041文字が返りました。一方Claude Codeは、MCPの出力が10,000トークンを超えると警告し、既定25,000トークンで制限し、5万文字を超えるテキストの結果はファイルへ退避します。既定や20000では、切り詰めた後もClaude Code側でファイル送りになります。切られたJSONは途中で途切れ、後半の課題が欠けた状態です。MAX_TOKENS=10000 を目安にし、足りない一覧は件数指定と次の fields で小さくしてください。
OPTIMIZE_RESPONSEのfieldsに対応する一覧系22ツール
OPTIMIZE_RESPONSE=1 を足すと、一覧を返すツールに fields 引数が加わり、必要な最上位の項目だけを返させられます。0.23.2で数えると対象は get_issues・get_project_list・get_pull_requests など22ツールで、get_issue のような1件を返すツールには付きません。項目名は列挙型で公開されるため、存在しない名前は無視されずにエラーになります。
代わりにツール定義が膨らみ、実測では同じ数え方のツール定義が51,362文字から58,615文字へ約14%増えました。get_issues を id・issueKey・summary・status に絞る使い方なら、応答の削減のほうが大きくなります。
削除系ツールをクライアントの権限設定で封じる設計
サーバー側で絞れるのはツールセットの有無だけです。削除を防ぐには、AIクライアント側の権限設定で止めます。ツール単位の権限設計の考え方はMCPサーバーのツール定義と認可の実装手順で一般化して整理しています。
0.20.6で付いた破壊的ヒントの12ツールとdelete_versionの名前のずれ
toolAnnotations.ts はツール名の先頭の動詞でヒントを決めています。get・count・list は読み取り、add は破壊的でない書き込み、update・delete・remove は破壊的です。値を上書きする update_issue も削除と同じ扱いになります。
issue を有効にすると、delete_issue・delete_version・delete_watching・remove_related_issue もAIが呼べる状態になります。落とし穴は名前です。READMEのツール一覧はマイルストーン削除を delete_version_milestone と書いていますが、0.23.2のソースが登録する名前は delete_version で、tools/list にもこの名前で出ました。READMEの名前で拒否ルールを書くと、何も止まりません。
readOnlyHintでは確認が省かれないClaude Codeのsettings.json
Claude CodeのMCPドキュメントで readOnlyHint に結び付いている動作は、読み取り同士の並列実行と、接続が切れたときの再試行です。確認の要否は従来どおり permissions で決まります。権限設定のドキュメントによると、denyとaskのルールはツール名の位置にglobを書けますが、allowのglobを使える位置は mcp__<サーバー名>__ の後ろだけです。.claude/settings.json に次のように書きます。
{
"permissions": {
"allow": ["mcp__backlog__get_*", "mcp__backlog__count_*"],
"ask": ["mcp__backlog__add_*", "mcp__backlog__update_*"],
"deny": ["mcp__backlog__delete_*", "mcp__backlog__remove_*"]
}
}読み取りは確認なしで通り、起票と更新は毎回確認が入り、削除系はAIの文脈から外れます。名前に _ や * を含むルールはタイプミス検出の警告対象外なので、実在しない名前を書いても警告は出ません。個別名より delete_* のglobが確実です。PREFIX を付けた場合は mcp__backlog__backlog_delete_* になる点にも注意してください。
APIキーの発行ユーザーに基づくAIの操作範囲
Backlog APIの認証ドキュメントのとおり、APIキーはユーザーごとに発行され、そのユーザーとして動きます。スペース管理者のキーを渡せば、AIもスペース管理者です。クライアント側のdenyは設定を書き換えれば外れるため、守りたい線は、参加プロジェクトと役割を絞ったユーザーのキーを使うことで引きます。
プロジェクトを限定できるRust版BACKLOG_PROJECTSとの選び分け
ヌーラボの社員が個人開発したsafx/backlog-mcp-server-rustもあり、2026年10月8日にv0.1.6が出ています（ヌーラボ公式ブログの紹介記事）。公式版に無いのは、環境変数 BACKLOG_PROJECTS でプロジェクトキーを限定できることと、issue_writable などのCargoのfeatureを外して書き込み系をバイナリから除けることです。既定のビルドでは書き込み系が有効です。1つのAPIキーで複数の顧客プロジェクトが見え、それをサーバー側で遮断したい場面に限って、自分でビルドする価値があります。
ユーザー単位のレート制限とAIの並列呼び出しで起きる429
AIが課題ごとの詳細取得を繰り返すと、APIの呼び出しが増えます。課題一覧で必要な情報を取得できる場合は、一覧取得を優先してください。
ユーザー単位で共有されるBacklog APIのレート制限
Backlog APIのレート制限は、ユーザーごとに1分あたりのリクエスト数を、読み込み・更新・検索・アイコンの4種別で制限します。課題一覧の取得と課題数の取得は「検索」に入るため、AIが get_issues を繰り返すと検索の枠から減ります。英語版の同じページは、制限はAPIキー単位ではなくユーザー単位で、同じユーザーが作ったキーAとキーBは同じ枠を共有すると明記しています。
MCP用に同じユーザーで2本目のキーを作っても、社内の連携スクリプトと枠を取り合う状態は変わりません。切り分けたいならMCP専用のユーザーを作ってキーを発行します。ドキュメントは1つのソフトウェアが複数ユーザーのキーを使い回すことを推奨しておらず、枠を増やす目的でキーを回す使い方は利用停止の対象になりえます。
/api/v2/rateLimitによる上限確認と並列呼び出しの見積もり
上限値はプランと種別で異なり、レート制限情報の取得APIで自分の値を確かめる方式です。
curl -s "https://your-space.backlog.com/api/v2/rateLimit" \
-H "Backlog-API-Key: $BACKLOG_API_KEY"ドキュメントの応答例では、読み込みが毎分600回、更新と検索が毎分150回、アイコンが毎分60回です。同じページは、1ユーザーのリクエストを同時に送らず直列にすることを勧めています。一方、Claude Codeは readOnlyHint の付いた呼び出しを他の読み取りと並列に実行します。0.20.6以降は get_* が並んで飛ぶ前提で、429が返ったら1分待つよう指示文や CLAUDE.md に書いておくと、AIが失敗を繰り返して枠を使い切る事態を防げます。
APIキー共有を避けるOAuth 2.0のHTTPモード
個人のAPIキーを各自の端末に置く運用が許されない組織向けに、公式版はOAuth 2.0で動くHTTPモードを持っています。
HTTPトランスポートとOAuthアプリ登録で社内に1台立てる構成
READMEの手順は、Backlogでアプリケーションを登録し、リダイレクトURIに <MCP_SERVER_BASE_URL>/callback を設定するところから始まります。この例はソースを取得して依存関係の導入とビルドを済ませ、リポジトリ直下で実行する前提です。公開URLからHTTP待受先へのHTTPSリバースプロキシを構成したうえで、得たクライアントIDとシークレットを渡して起動します。
BACKLOG_DOMAIN=your-space.backlog.com \
BACKLOG_OAUTH_CLIENT_ID=your-client-id \
BACKLOG_OAUTH_CLIENT_SECRET=your-client-secret \
MCP_SERVER_BASE_URL=https://mcp.example.com \
node build/index.js --transport http --http-host 0.0.0.0 --http-port 3333 \
--http-allowed-hosts mcp.example.com利用者は自分のBacklogアカウントで認可するので、APIキーを誰にも渡さずに済みます。サーバーは認可サーバーのメタデータと動的クライアント登録の /register を自動で公開します。0.0.0.0 で待ち受けるときは、DNSリバインディング対策として --http-allowed-hosts が実質必須です。
単一スペース・メモリ保存・1時間で失効するトークンの制約
READMEによると、OAuthモードは単一のスペースにしか対応せず、複数スペースの設定とは併用できません。クライアント登録とトークンはメモリに保持されるため、再起動のたびに全員が認可をやり直します。コンテナを頻繁に入れ替える基盤には向きません。Backlogのアクセストークンは、認証ドキュメントのとおり発行から3600秒で失効し、リフレッシュトークンで更新されます。
Backlog MCPを社内展開してよい条件と見送るべき運用
個人のAPIキーで始めてよい開発チームと共有アカウント運用の禁止
採用してよいのは、開発者が自分のAPIキーで、自分が担当する課題を読み書きする使い方です。Backlog上の操作履歴は本人名義で残り、AIの操作も本人の操作として追えます。deny設定を .claude/settings.json としてリポジトリに入れれば、全員に同じ歯止めが掛かります。
見送るべきなのは、共有アカウントのAPIキーを配る運用です。誰のAIが課題を書き換えたのか、Backlogの履歴から区別できなくなります。退職者の端末にキーが残ったとき、共有キーを削除すればアクセスを止められますが、継続利用する全員に新しいキーの配布と設定変更が必要です。レート制限もそのユーザー1人分の枠を全員で分け合うことになります。人数が増えたら、キーの配布ではなく前述のOAuthモードへ移る判断になります。ツールの選び直しから検討するならプロジェクト管理ツールの選び方と既製か自作かの判断軸も参考になります。
顧客とのBacklogを扱う受託案件でMCPを見送る場面と代替策
顧客のスペースにゲストとして招かれている場合は、原則として接続しません。課題本文や添付ファイルがAIの文脈に流れ、利用しているAIサービスの規約に沿って外部へ送信されるためです。接続を検討するなら、契約・秘密保持義務・顧客の情報管理ルールを確認し、対象データと利用するAIサービスについて顧客の許可を得てください。
顧客の了承が取れた場合でも、公式版のツールセット設定だけに頼らず、参加プロジェクトを絞った専用ユーザーのキーを使う構成にしてください。課題管理とAIエージェントを業務フローに組み込む仕組みを、権限と監査の設計から作りたい場合は、生成AI開発・AI受託開発の範囲でご相談いただけます。
よくある質問
Backlog MCPサーバーは無料で使えますか？
MCPサーバー自体はMITライセンスのOSSで、利用料はかかりません。必要なのはBacklogの契約とAPIキー、接続するAIクライアント側の利用料です。ヌーラボのサポート窓口は対象外で、不具合はGitHubのIssuesへ報告します。
CodexやCursor、clineでも同じ設定で動きますか？
動きます。command と env で標準入出力のサーバーを起動する形式は各クライアントで共通で、違うのは設定ファイルの置き場所と削除系の止め方です。Claude Code・Codex以外では各製品のツール承認設定を使うか、ENABLE_TOOLSETS で書き込みの多いツールセットを外してください。
Backlog MCPで課題を読み取り専用にできますか？
公式版のサーバー設定だけではできません。0.20.6で付いた読み取り専用かどうかのヒントを使って書き込みを止めるのはクライアントの役目で、Claude Codeなら add_*・update_*・delete_*・remove_* に加え、mark_*・reset_* もサーバー名付きのdenyルールに入れると、0.23.2の書き込みツールを拒否できます。サーバー側で除くならRust版をfeatureを外してビルドします。
Backlog MCPでドキュメントや添付ファイルも読めますか？
読めます。document ツールセットでドキュメントの階層、本文、コメントを取得でき、0.22.0からは本文がプレーンテキストで返り、start と limit で長い文書を分けて読めます。課題の添付ファイルは0.19.0で追加された get_issue_attachment で取得します。Wikiの添付や共有ファイルまで読ませたい場合はRust版が選択肢です。添付の中身はAIの文脈に入るため、機密資料のあるプロジェクトは対象から外してください。
複数のBacklogスペースを1つの設定で扱えますか？
APIキー方式なら扱えます。BACKLOG_DEFAULT_ORG と、BACKLOG_ORG_<名前>_DOMAIN・BACKLOG_ORG_<名前>_API_KEY の組を並べると、各ツールに organization 引数が加わります（OAuthモードとは併用不可）。自社と顧客のスペースを両方登録すると、AIが取り違えて顧客側に起票しかねないため、受託ではスペースごとに設定を分けてください。
