Backlog MCP Server

Backlog MCP サーバー

📘 日本語でのご利用ガイド

Backlog API と連携するための Model Context Protocol（MCP）サーバーです。このサーバーを使用すると、Claude Desktop／Cline／Cursor などの AI エージェントを通じて、Backlog のプロジェクト、課題、Wiki ページなどを管理できます。

特長

• プロジェクトツール（作成、読み取り、更新、削除）
• 課題の追跡とコメント（作成、更新、削除、一覧表示）
• バージョン／マイルストーンの管理（作成、読み取り、更新、削除）
• Wiki ページのサポート
• Git リポジトリとプルリクエストのツール
• 通知ツール
• 応答を最適化するフィールド選択
• 大きな応答のトークン制限

はじめに

必要条件

• Docker
• API を利用できる Backlog アカウント
• Backlog アカウントの API キー

オプション 1：Docker でインストール

この MCP サーバーを最も簡単に使用するには、MCP の設定を利用します。

1. MCP の設定を開きます
2. MCP の設定セクションに移動します
3. 次の設定を追加します

{
  "mcpServers": {
    "backlog": {
      "command": "docker",
      "args": [
        "run",
        "--pull",
        "always",
        "-i",
        "--rm",
        "-e",
        "BACKLOG_DOMAIN",
        "-e",
        "BACKLOG_API_KEY",
        "ghcr.io/nulab/backlog-mcp-server"
      ],
      "env": {
        "BACKLOG_DOMAIN": "your-domain.backlog.com",
        "BACKLOG_API_KEY": "your-api-key"
      }
    }
  }
}

your-domain.backlog.com をお使いの Backlog ドメインに、your-api-key を Backlog API キーに置き換えてください。

✅ --pull always を使用できない場合は、次の手順でイメージを手動で更新できます。

docker pull ghcr.io/nulab/backlog-mcp-server:latest

オプション 2：npx でインストール

リポジトリをクローンせずに、npx を使ってサーバーを直接実行することもできます。完全にインストールすることなくサーバーを実行できる便利な方法です。

1. MCP の設定を開きます
2. MCP の設定セクションに移動します
3. 次の設定を追加します

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

your-domain.backlog.com をお使いの Backlog ドメインに、your-api-key を Backlog API キーに置き換えてください。

オプション 3：手動セットアップ（Node.js）

1. クローンしてインストールします。

   git clone https://github.com/nulab/backlog-mcp-server.git
   cd backlog-mcp-server
   pnpm install
   pnpm run build
   

2. テンプレートから .env を作成し、必要な変数を設定します。

cp .env.example .env

.env に次の値を設定します。

• BACKLOG_DOMAIN=your-domain.backlog.com
• BACKLOG_API_KEY=your-api-key

3. ローカルで実行します。

pnpm run dev

4. MCP として使用する JSON を設定します

{
  "mcpServers": {
    "backlog": {
      "command": "node",
      "args": ["your-repository-location/build/index.js"],
      "env": {
        "BACKLOG_DOMAIN": "your-domain.backlog.com",
        "BACKLOG_API_KEY": "your-api-key"
      }
    }
  }
}

HTTP トランスポート（Streamable HTTP）

デフォルトでは、サーバーは stdio を使用します。代わりに MCP Streamable HTTP トランスポート（HTTP 経由の JSON-RPC。stdio と同じツール）を実行するには、--transport http を指定して起動するか、MCP_TRANSPORT=http を設定します。

pnpm run build
MCP_TRANSPORT=http MCP_HTTP_PORT=3333 node build/index.js

• エンドポイント： http://<host>:<port><path> への POST（サーバー起動ストリームでは GET も使用）。デフォルトのパスは /mcp です。
• プロトコル： MCP 2026-07-28。プロトコルはステートレスです。initialize のハンドシェイクも mcp-session-id ヘッダーもありません。クライアントはすべてのリクエストで _meta にメタデータを送信し、server/discover を通じて機能を検出します。Streamable HTTP では Mcp-Method ヘッダー（および tools/call では Mcp-Name）も必要です。
• 下位互換性： 2025-11-25 以前のクライアントも、同じエンドポイントを通じてステートレスに利用できます。セッションが保持されないため、2025 年のセッション操作（mcp-session-id を指定した GET／DELETE）は 405 を返します。
• セキュリティ： デフォルトのバインド先は 127.0.0.1 です。ループバックに直接バインドする場合、Host と Origin はどちらも localhost のリストと照合されます（DNS リバインディング対策）。リバースプロキシの背後では、公開ホスト名を --http-allowed-hosts に設定してください。ブラウザクライアントの Origin はクライアント自身のサイトを示し、このサーバーのホスト名にはならないため、これにより localhost の Origin のデフォルト設定は無効になります。サーバーへの接続を許可するクライアントのオリジンを制限するには、--http-allowed-origins を追加してください。認証と TLS を使用せずに、信頼できないネットワークへ HTTP ポートを公開しないでください。MCP ツールを通じて Backlog API キーを全面的に使用できてしまいます。

環境変数（両方が設定されている場合は CLI フラグが優先されます）：

変数	説明
MCP_TRANSPORT	stdio（デフォルト）または http
MCP_HTTP_HOST	バインドアドレス（デフォルトは 127.0.0.1）
MCP_HTTP_PORT	ポート（デフォルトは 3333）
MCP_HTTP_PATH	URL パス（デフォルトは /mcp）
MCP_HTTP_JSON_RESPONSE	SSE より JSON レスポンスを優先する場合は true（2026-07-28 クライアントのみに適用）
MCP_HTTP_ALLOWED_HOSTS	許可する Host のホスト名（ポートは無視）のカンマ区切りリスト。0.0.0.0 にバインドする場合は必須です。プロキシの背後でループバックにバインドする場合にも使用します（DNS リバインディング対策）
MCP_HTTP_ALLOWED_ORIGINS	ブラウザベースのクライアントに許可する Origin のホスト名のカンマ区切りリスト。ループバックに直接バインドする場合は localhost のリストがデフォルトとなり、それ以外の場合は Origin のチェックは行われません

OAuth 2.0 認証（リモート MCP）

ネットワーク経由で MCP サーバーを公開する場合、OAuth 2.0 認証を有効にして、単一の API キーを共有する代わりに、各ユーザーが自分の Backlog アカウントで認証できるようにできます。

このサーバーは、OAuth 認可サーバー（MCP クライアント向け）と OAuth クライアント（Backlog 向け）の両方として動作することで、MCP Third-Party Authorization Flow を実装しています。

前提条件

1. Backlog スペースに OAuth アプリケーションを登録します。

   • Backlog スペース → 個人設定 → アプリケーション登録に移動します
   • Redirect URI を <MCP_SERVER_BASE_URL>/callback に設定します（例：https://mcp.example.com/callback）
   • Client ID と Client Secret を控えておきます

2. BACKLOG_DOMAIN に加えて、以下の環境変数を設定します。

変数	説明
BACKLOG_OAUTH_CLIENT_ID	Backlog アプリケーションの OAuth Client ID
BACKLOG_OAUTH_CLIENT_SECRET	Backlog アプリケーションの OAuth Client Secret
MCP_SERVER_BASE_URL	MCP サーバーの公開 URL（例：https://mcp.example.com）

注： OAuth が有効な場合、BACKLOG_API_KEY は不要です。各ユーザーが自身の Backlog アカウントで認証します。

例

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

0.0.0.0 にバインドする場合、実運用では --http-allowed-hosts が必要です。これを指定しないと DNS リバインディング保護が行われず、サーバーの起動時に警告がログに記録されます。

OAuth が有効な場合、サーバーは以下の OAuth エンドポイントを自動的に公開します。

エンドポイント	説明
GET /.well-known/oauth-authorization-server	OAuth 認可サーバーメタデータ（RFC 8414）
GET /.well-known/oauth-protected-resource/mcp	OAuth 保護リソースメタデータ（RFC 9728）
POST /register	動的クライアント登録（RFC 7591）
GET /authorize	認可エンドポイント（Backlog OAuth にリダイレクトします）
GET /callback	Backlog OAuth コールバック
POST /token	トークンエンドポイント（認可コードとリフレッシュトークン）

MCP 認可仕様をサポートする MCP クライアントは、これらのエンドポイントを自動的に使用します。

POST /register は、クライアントが登録できるリダイレクト URI を制限します。ループバック URI（http://localhost、http://127.0.0.1、http://[::1]）は、ユーザーのマシンで実行されているアプリが認可コードを受け取るためのもので、"application_type": "native" を宣言したクライアントからの登録は受け入れられます。また、フィールドがない場合は、すべてのリダイレクト URI がループバックであるクライアントからの登録も受け入れられます。"application_type": "web" を宣言したクライアント、または自身がネイティブであると宣言せずにリモートの https: URI とループバック URI を混在させたクライアントは、invalid_client_metadata で拒否されます。

制限事項：

• OAuth モードは現在、単一の Backlog 組織のみをサポートします。複数組織の構成には対応していません。
• クライアント登録とトークンはメモリに保存されるため、サーバーを再起動すると失われます。

ツールの設定

--enable-toolsets コマンドラインフラグまたは ENABLE_TOOLSETS 環境変数を使用して、特定のツールセットを選択的に有効化または無効化できます。これにより、AI エージェントが利用できるツールをより細かく制御でき、コンテキストサイズの削減にも役立ちます。

利用可能なツールセット

以下のツールセットを利用できます（"all"を使用すると、デフォルトですべて有効になります）。

ツールセット	説明
space	Backlog のスペース設定と一般情報を管理するツール
project	プロジェクト、カテゴリ、カスタムフィールド、課題種別を管理するツール
issue	課題、そのコメント、バージョンマイルストーンを管理するツール
wiki	Wiki ページを管理するツール
git	Git リポジトリとプルリクエストを管理するツール
notifications	ユーザー通知を管理するツール
document	ドキュメントとドキュメントツリーを表示するツール

ツールセットの指定

以下の方法で、ツールセットを有効化できます。

CLI を使用する場合：

--enable-toolsets space,project,issue

または、環境変数を使用する場合：

ENABLE_TOOLSETS="space,project,issue"

allを指定すると、利用可能なすべてのツールセットが有効になります。これがデフォルトの動作でもあります。

AI エージェントでツールセットのリストが大きすぎる場合や、特定のツールがパフォーマンスの問題を引き起こしている場合は、ツールセットを選択して使用すると便利です。そのような場合、使用していないツールセットを無効にすると、安定性が向上することがあります。

🧩 ヒント：他の多くのツールがプロジェクトデータをエントリーポイントとして利用するため、projectツールセットを強く推奨します。

利用可能なツール

ツールセット：space

Backlog のスペース設定と一般情報を管理するツールです。

• get_space：Backlog スペースの情報を返します。
• get_users：Backlog スペースのユーザー一覧を返します。
• get_myself：認証済みユーザーの情報を返します。

ツールセット：project

プロジェクト、カテゴリ、カスタムフィールド、課題種別を管理するツールです。

• get_project_list：プロジェクト一覧を返します。
• add_project：新しいプロジェクトを作成します。
• get_project：特定のプロジェクトの情報を返します。
• get_project_users：特定のプロジェクトのユーザー一覧を返します。
• update_project：既存のプロジェクトを更新します。

ツールセット：issue

課題、課題へのコメント、優先度、カテゴリー、カスタムフィールド、課題の種類、解決状況、ウォッチリストなどの関連項目を管理するツールです。

• get_issue：特定の課題の情報を取得します。
• get_issue_attachment：課題の添付ファイルを1つダウンロードします。画像または埋め込みリソースのコンテンツとして、あるいは format: "base64" を指定した場合は base64 として返します。
• get_issues：課題の一覧を取得します。
• count_issues：課題の件数を取得します。
• add_issue：指定したプロジェクトに新しい課題を作成します。
• update_issue：既存の課題を更新します。
• delete_issue：課題を削除します。
• get_issue_comments：課題へのコメント一覧を取得します。
• add_issue_comment：課題にコメントを追加します。
• update_issue_comment：課題へのコメントを更新します。
• get_related_issues：特定の課題に関連する課題の一覧を取得します。
• add_related_issue：ある課題を別の課題に関連付けます。
• remove_related_issue：課題と関連課題の関連付けを解除します。
• get_priorities：優先度の一覧を取得します。
• get_categories：プロジェクトのカテゴリー一覧を取得します。
• add_category：プロジェクトに新しいカテゴリーを作成します。
• get_custom_fields：プロジェクトのカスタムフィールド一覧を取得します。
• get_issue_types：プロジェクトの課題の種類の一覧を取得します。
• get_resolutions：課題の解決状況の一覧を取得します。
• get_watching_list_items：ユーザーのウォッチ項目の一覧を取得します。
• get_watching_list_count：ユーザーのウォッチ項目の件数を取得します。
• add_watching：課題を新たにウォッチします。
• update_watching：既存のウォッチメモを更新します。
• delete_watching：課題のウォッチを削除します。
• mark_watching_as_read：ウォッチ項目を既読にします。
• get_version_milestone_list：プロジェクトのバージョンマイルストーン一覧を取得します。
• add_version_milestone：プロジェクトに新しいバージョンマイルストーンを作成します。
• update_version_milestone：既存のバージョンマイルストーンを更新します。
• delete_version_milestone：バージョンマイルストーンを削除します。

ツールセット：wiki

Wiki ページを管理するツールです。

• get_wiki_pages：Wiki ページの一覧を取得します。
• get_wikis_count：プロジェクトの Wiki ページ数を取得します。
• get_wiki：特定の Wiki ページの情報を取得します。
• add_wiki：新しい Wiki ページを作成します。

ツールセット：git

Git リポジトリとプルリクエストを管理するツールです。

• get_git_repositories：プロジェクトの Git リポジトリ一覧を取得します。
• get_git_repository：特定の Git リポジトリの情報を取得します。
• get_pull_requests：リポジトリのプルリクエスト一覧を取得します。
• get_pull_requests_count：リポジトリのプルリクエスト件数を取得します。
• get_pull_request：特定のプルリクエストの情報を取得します。
• add_pull_request：新しいプルリクエストを作成します。
• update_pull_request：既存のプルリクエストを更新します。
• get_pull_request_comments：プルリクエストへのコメント一覧を取得します。
• add_pull_request_comment：プルリクエストにコメントを追加します。
• update_pull_request_comment：プルリクエストへのコメントを更新します。

ツールセット：notifications

ユーザー通知を管理するツールです。

• get_notifications：通知の一覧を取得します。
• get_notifications_count：通知の件数を取得します。
• reset_unread_notification_count：未読通知数をリセットします。
• mark_notification_as_read：通知を既読にします。

ツールセット：document

Backlog プロジェクトのドキュメントとドキュメントツリーを管理するツールです。

• get_document_tree：フォルダーや ne を含む、プロジェクトのドキュメントの階層ツリーを取得します。
• get_documents：プロジェクトまたはフォルダー内のドキュメントのフラットな一覧を取得します。
• get_document_comments：返信を含む、ドキュメントへのコメントを取得します。
• get_document：メタデータ、コンテンツ、an を含む、特定のドキュメントの詳細情報を取得します。

使用例

MCP サーバーを AI エージェントに設定すると、会話の中でツールを直接使用できます。例をいくつか紹介します。

• プロジェクトの一覧表示

Could you list all my Backlog projects?

• 新しい課題の作成

Create a new bug issue in the PROJECT-KEY project with high priority titled "Fix login page error"

• プロジェクトの詳細情報の取得

Show me the details of the PROJECT-KEY project

• Git リポジトリの操作

List all Git repositories in the PROJECT-KEY project

• プルリクエストの管理

Show me all open pull requests in the repository "repo-name" of PROJECT-KEY project

Create a new pull request from branch "feature/new-feature" to "main" in the repository "repo-name" of PROJECT-KEY project

• 項目のウォッチ

Show me all items I'm watching

ツールの説明の上書き

ホームディレクトリに .backlog-mcp-serverrc.json ファイルを作成すると、ツールの説明を上書きできます。

これらの文字列のほとんどは、モデルが呼び出すツールと引数の設定方法を決める際に読み取る、ツールやパラメーターの説明です。そのため、これらを上書きするのは、回答の言語を変更するためではなく、ツールの選択を誘導するための方法です。たとえば、よく似たツールを区別したり、チームで遵守しているルールを追加したりできます。これらの説明が何語で書かれているかにかかわらず、モデルはユーザーが指定した言語で回答します。

一部のキーは、検証エラーメッセージです（例：PROJECT_ID_OR_KEY_REQUIRED）。これらは呼び出しが拒否されたときにツールの結果として返され、モデルの返信を介してユーザーに届く場合があります。

このファイルには、ツール名をキー、新しい説明を値とする JSON オブジェクトを記述してください。
例：

{
  "TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "An alternative description",
  "TOOL_CREATE_PROJECT_DESCRIPTION": "Create a new project in Backlog"
}

サーバーの起動時に、次の優先順位に基づいて各ツールの最終的な説明が決定されます。

1. 環境変数（例：BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION）
2. .backlog-mcp-serverrc.json のエントリー - 対応する設定ファイル形式：.json、.yaml、.yml
3. 組み込みのデフォルト値

どのレベルでも、空の値または文字列以外の値は無視され、代わりに組み込みのデフォルト値が使用されます。

設定例：

{
  "mcpServers": {
    "backlog": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "BACKLOG_DOMAIN",
        "-e",
        "BACKLOG_API_KEY",
        "-v",
        "/yourcurrentdir/.backlog-mcp-serverrc.json:/root/.backlog-mcp-serverrc.json:ro",
        "ghcr.io/nulab/backlog-mcp-server"
      ],
      "env": {
        "BACKLOG_DOMAIN": "your-domain.backlog.com",
        "BACKLOG_API_KEY": "your-api-key"
      }
    }
  }
}

現在の説明のエクスポート

--export-descriptions フラグを指定してバイナリを実行すると、現在の説明（上書き内容を含む）をエクスポートできます。このフラグは以前 --export-translations という名前でした。古い名前も引き続き使用できますが、非推奨の通知が表示され、今後のリリースで削除される予定です。

このコマンドは、ツールリストの構築時に解決されるすべてのキーと、その現在の値を出力します。これには、ユーザーが行ったカスタマイズも含まれます。すべてのツールとパラメーターの説明が対象となるため、キー名を確認する実用的な方法です。

検証エラーメッセージは対象外です。これらのキーは、呼び出しが実際に拒否されたときにのみ解決されるためです。同じルールで引き続き上書きできますが、ソースから読み取る必要があります。

例：

docker run -i --rm ghcr.io/nulab/backlog-mcp-server node build/index.js --export-descriptions

または

npx github:nulab/backlog-mcp-server --export-descriptions

環境変数の使用

ツールの説明は、環境変数を使って上書きすることもできます。

環境変数名はツールキーを基にし、BACKLOGMCP を先頭に付けて大文字で記述します。

例： TOOL_ADD_ISSUE_COMMENT_DESCRIPTION を上書きするには：

{
  "mcpServers": {
    "backlog": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "BACKLOG_DOMAIN",
        "-e", "BACKLOG_API_KEY",
        "-e", "BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION"
        "ghcr.io/nulab/backlog-mcp-server"
      ],
      "env": {
        "BACKLOG_DOMAIN": "your-domain.backlog.com",
        "BACKLOG_API_KEY": "your-api-key",
        "BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "An alternative description"
      }
    }
  }
}

サーバーは起動時に設定ファイルを同期的に読み込みます。

環境変数は常に設定ファイルより優先されます。

高度な機能

ツール名へのプレフィックスの追加

次のコマンドでツール名にプレフィックスを追加します。

--prefix backlog_

または、環境変数を使用します。

PREFIX="backlog_"

これは、同じ環境で複数の MCP サーバーまたはツールを使用していて、名前の衝突を避けたい場合に特に便利です。たとえば、get_project を backlog_get_project に変更すると、他のサービスが提供する同名のツールと区別できます。

レスポンスの最適化とトークン制限

レスポンスの圧縮

ツールの結果は返される前に圧縮されます。これは常に有効で、ファイル自体を返す get_issue_attachment を除くすべてのツールに適用されます。

• 結果内にネストされたユーザー（createdUser、assignee、stars[].presenter、通知の sender など）は、id、userId、name のみに縮小されます。結果そのものがユーザーである場合（get_myself、get_users または get_project_users の各項目）は、全体が返されます。
• ネストされたプロジェクト（各アクティビティおよび通知の project）は id、projectKey、name のみに縮小され、ネストされた課題（プルリクエストまたは通知の issue）は id、issueKey、summary、status のみに縮小されます。結果そのものがプロジェクトまたは課題である場合（get_project、get_issue、get_project_list または get_issues の各項目）は全体が返され、get_watching_list_items の各項目の課題も同様に全体が返されます。
• ネストされたエンティティ（ステータス、課題タイプ、カテゴリー、マイルストーン、カスタムフィールド項目など）では、color と displayOrder が省略され、ネストされたマイルストーンでは description も省略されます。これらのエンティティ自体を一覧表示するツール（get_issue_types、get_categories、get_version_milestone_list など）は、全体を返します。
• null、空文字列、空配列のフィールドは省略されます。0、false、{} は保持されます。これは fields で指定されたフィールドにも適用され、空のフィールドは空のまま返されず、省略されます。
• JSON はインデントなしで返されます。

フィールドの選択

--optimize-response

または、環境変数で設定します。

OPTIMIZE_RESPONSE=1

リストを返すツールでは、省略可能な fields パラメーターを指定できます。このパラメーターには、そのツール自身の結果に含まれるトップレベルのフィールド名のリストを指定します。フィールド名は列挙型として公開されるため、ツールに存在しない名前は無視されず、拒否されます。単一のレコードを返すツールにはこのパラメーターはありません。毎回のセッションでスキーマのコストがかかる一方、単一レコードでは削減できる内容がほとんどないためです。

get_project(projectIdOrKey: "PROJECT-KEY", fields: ["name", "key", "description"])

fields を省略すると、結果全体が返されます。選択は1階層のみです。オブジェクトまたは配列のフィールドを指定すると、その全体が返されます。

メリット：

• 必要なフィールドだけを要求してレスポンスサイズを削減できます
• 特定のデータポイントに焦点を当てられます
• 大きなレスポンスのパフォーマンスを改善できます

トークン制限

トークン制限を超えないよう、大きなレスポンスは自動的に制限されます。

• デフォルトの制限：50,000 トークン
• MAX_TOKENS 環境変数で設定可能
• 制限を超えるレスポンスは、メッセージとともに切り詰められます

次の方法で変更できます。

MAX_TOKENS=10000

レスポンスが制限を超えると、警告とともに切り詰められます。

注意：これは可能な範囲での緩和策であり、制限の適用を保証するものではありません。

ログ

サーバーは stderr にログを出力します（stdio トランスポートでは、stdout に JSON-RPC ストリームが出力されます）。

変数	説明
LOG_LEVEL	fatal、error、warn、info、debug、trace または silent を指定します。デフォルトは、NODE_ENV が production の場合（NODE_ENV が未設定の場合もデフォルトで production です）は error、それ以外の場合は debug です。認識されない値が指定された場合は、その旨が報告され、デフォルト値が使用されます。

NODE_ENV は引き続き出力の形式を選択します。production 以外の値にすると、pino-pretty パッケージが利用可能な場合は、人間が読みやすい出力に切り替わります。デプロイ環境で構造化 JSON を維持するには、ログの出力量を変更するために NODE_ENV ではなく LOG_LEVEL を使用してください。

pino-pretty は開発用の依存関係であるため、公開されている npm パッケージにもコンテナーイメージにも含まれていません。そのため、これらの環境では NODE_ENV の値にかかわらずログは構造化 JSON となり、出力を変更する設定は LOG_LEVEL のみです。

LOG_LEVEL=info node build/index.js --transport http

カスタム設定の詳細な例

このセクションでは、複数の環境変数を使用した高度な設定について説明します。これらは実験的な機能であり、すべての MCP クライアントでサポートされるとは限りません。MCP 標準仕様の一部ではないため、注意して使用してください。

{
  "mcpServers": {
    "backlog": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "BACKLOG_DOMAIN",
        "-e",
        "BACKLOG_API_KEY",
        "-e",
        "MAX_TOKENS",
        "-e",
        "OPTIMIZE_RESPONSE",
        "-e",
        "PREFIX",
        "-e",
        "ENABLE_TOOLSETS",
        "ghcr.io/nulab/backlog-mcp-server"
      ],
      "env": {
        "BACKLOG_DOMAIN": "your-domain.backlog.com",
        "BACKLOG_API_KEY": "your-api-key",
        "MAX_TOKENS": "10000",
        "OPTIMIZE_RESPONSE": "1",
        "PREFIX": "backlog_",
        "ENABLE_TOOLSETS": "space,project,issue"
      }
    }
  }
}

開発

テストの実行

pnpm test

新しいツールの追加

1. 既存のツールのパターンに従って、src/tools/ に新しいファイルを作成します
2. 対応するテストファイルを作成します
3. src/tools/tools.ts に新しいツールを追加します
4. 変更をビルドしてテストします

コマンドラインオプション

サーバーはいくつかのコマンドラインオプションに対応しています。

• --transport stdio|http：MCP トランスポート（デフォルト：stdio）。Streamable HTTP を使用する場合は http を指定します。
• --http-host、--http-port、--http-path：HTTP のバインドアドレス、ポート、パス（デフォルトはそれぞれ 127.0.0.1、3333、/mcp）。
• --http-json-response：SSE よりも JSON レスポンスを優先します。2026-07-28 のクライアントにのみ適用されます。下位互換性のある 2025-11-25 のパスでは、SDK のデフォルトのレスポンス形式が使用されます。
• --http-allowed-hosts：許可する Host ホスト名をコンマ区切りで指定します（ポートは無視されます）。すべてのインターフェイスにバインドする場合、またはループバックへのバインド時にリバースプロキシの背後で使用する場合に必要です。
• --http-allowed-origins：ブラウザーベースのクライアントに対して許可する Origin ホスト名をコンマ区切りで指定します。ループバックに直接バインドする場合は localhost の一覧がデフォルトになり、それ以外の場合は Origin の確認を行いません。
• --export-descriptions：ツール一覧の作成時に解決された説明のキーと値をエクスポートします。以前は --export-translations という名前でした。この表記も非推奨のエイリアスとして引き続き使用できますが、今後のリリースで削除されます。
• --optimize-response：返す結果フィールドを選択するための fields パラメーターを各ツールに追加します
• --max-tokens=NUMBER：レスポンスの最大トークン数を設定します
• --prefix=STRING：すべてのツール名の先頭に付ける任意の文字列（デフォルト：""）
• --enable-toolsets <toolsets...>：有効にするツールセットを指定します（コンマ区切り、または複数の引数で指定）。デフォルトは「all」です。 例：--enable-toolsets space,project または --enable-toolsets issue --enable-toolsets git 使用可能なツールセット：space、project、issue、wiki、git、notifications。

例：

node build/index.js --optimize-response --max-tokens=100000 --prefix="backlog_" --enable-toolsets space,issue

HTTP の例：

node build/index.js --transport http --http-port 3333 --http-path /mcp

複数組織のサポート

このサーバーは、1 つの MCP サーバーインスタンスから複数の Backlog 組織にアクセスできるように設定できます。

設定

組織ごとに環境変数のペアを設定し、デフォルトの組織を指定します。

BACKLOG_DEFAULT_ORG=COMPANY_A
BACKLOG_ORG_COMPANY_A_DOMAIN=company-a.backlog.com
BACKLOG_ORG_COMPANY_A_API_KEY=your-company-a-api-key
BACKLOG_ORG_COMPANY_B_DOMAIN=company-b.backlog.com
BACKLOG_ORG_COMPANY_B_API_KEY=your-company-b-api-key

これらの変数は、ローカルの .env、シェル環境、または MCP クライアント設定の env ブロックのいずれに設定しても機能します。

MCP 設定の例：

{
  "env": {
    "BACKLOG_DEFAULT_ORG": "COMPANY_A",
    "BACKLOG_ORG_COMPANY_A_DOMAIN": "company-a.backlog.com",
    "BACKLOG_ORG_COMPANY_A_API_KEY": "your-company-a-api-key",
    "BACKLOG_ORG_COMPANY_B_DOMAIN": "company-b.backlog.com",
    "BACKLOG_ORG_COMPANY_B_API_KEY": "your-company-b-api-key"
  }
}

複数組織用の環境変数が設定されていない場合、サーバーは既存の単一組織設定にフォールバックします。

BACKLOG_DOMAIN=your-domain.backlog.com
BACKLOG_API_KEY=your-api-key

ツールの使用方法

複数組織用の環境変数が設定されている場合、通常のすべてのツールで省略可能な organization 入力フィールドを使用できます。このフィールドを指定すると、ツールの呼び出しは該当する Backlog 組織にルーティングされます。

単一組織モードでは、ルーティング先となる組織が 1 つしかないため、このフィールドは公開されません。このフィールドを省略することで、すべての tools/list レスポンスから約 8 KB のツールスキーマを除外できます。

例：

{
  "organization": "COMPANY_B",
  "projectKey": "PROJECT"
}

organization を省略した場合：

• BACKLOG_DEFAULT_ORG で指定された組織が使用されます
• 複数組織用の環境変数が設定されていて、BACKLOG_DEFAULT_ORG がない場合、サーバーは起動時に失敗します

組織の検出

複数組織モードでは、サーバーは設定済みの組織名、そのドメイン、およびデフォルトの組織を返す list_organizations ツールを提供します。このツールは単一組織モードでは登録されません。

レスポンスの例：

[
  {
    "name": "COMPANY_A",
    "domain": "company-a.backlog.com",
    "isDefault": true
  },
  {
    "name": "COMPANY_B",
    "domain": "company-b.backlog.com",
    "isDefault": false
  }
]

注意事項

• 複数組織モードでは、各組織に BACKLOG_ORG_<NAME>_DOMAIN と BACKLOG_ORG_<NAME>_API_KEY の両方を設定する必要があります。
• <NAME> の部分は、organization ツール入力および list_organizations で公開される組織名です。

ライセンス

このプロジェクトはMIT Licenseのもとでライセンスされています。

ご注意ください。このツールは、保証および公式サポートなしでMIT Licenseのもと提供されています。
内容を確認し、ご自身のニーズに適していると判断したうえで、自己責任でご利用ください。
問題が発生した場合は、GitHub Issuesからご報告ください。