Backlog MCP Server（日本語版）

April 2, 2026 · View on GitHub

MIT License Build Last Commit

🇬🇧 English README

Backlog API とやり取りするための Model Context Protocol（MCP）サーバーです。このサーバーは、Claude Desktop / Cline / Cursor などのAIエージェントを通じて、Backlog 上でプロジェクト、課題、Wikiページなどを管理するためのツールを提供します。

主な機能

  • プロジェクトツール（作成、読み取り、更新、削除）
  • 課題とコメントの追跡（作成、更新、削除、一覧表示）
  • 発生バージョン/マイルストーンの管理（作成、読み取り、更新、削除）
  • Wikiページサポート
  • Gitリポジトリとプルリクエストツール
  • 通知ツール
  • 最適化されたレスポンスのためのGraphQLスタイルのフィールド選択
  • 大規模なレスポンスに対するトークン制限

利用開始

必要条件

  • 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
npm install
npm run build

  2. テンプレートから .env を作成し、必須の環境変数を設定します：

cp .env.example .env

.env に以下を設定してください：

  • BACKLOG_DOMAIN=your-domain.backlog.com
  • BACKLOG_API_KEY=your-api-key
  1. ローカルで起動します：
npm run dev
  1. 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"
      }
    }
  }
}

ツール設定

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

利用可能なツールセット

次のツールセットが利用可能です（"all" が使用されるとデフォルトで有効になります）：

ツールセット説明
spaceBacklogスペース設定と一般情報を管理するためのツール
projectプロジェクト、カテゴリ、カスタムフィールド、課題タイプを管理するためのツール
issue課題とそのコメント、発生バージョン/マイルストーンを管理するためのツール
wikiWikiページを管理するためのツール
gitGitリポジトリとプルリクエストを管理するためのツール
notificationsユーザー通知を管理するためのツール
documentドキュメントおよびドキュメントツリーを参照するためのツール

ツールセットの指定

次の方法でツールセットのアクティベーションを制御できます：

CLI経由での使用：

--enable-toolsets space,project,issue

または環境変数経由：

ENABLE_TOOLSETS="space,project,issue"

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

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

🧩 ヒント: project ツールセットは、他の多くのツールがエントリポイントとしてプロジェクトデータに依存しているため、強く推奨されます。

動的なツールセット検出（実験的）

MCPサーバーをAIエージェントと共に使用している場合、実行時にツールセットの動的な検出を有効にすることができます：

CLI経由での有効化：

--dynamic-toolsets

または環境変数経由：

-e DYNAMIC_TOOLSETS=1 \

動的ツールセットを有効にすると、LLMはツールインターフェースを介してオンデマンドでツールセットを一覧表示およびアクティブ化できるようになります。

利用可能なツール

以下のような Backlog 機能に対応するツールを提供しています：

Available Tools セクションへ

使用例

MCPサーバーがAIエージェントで設定されると、会話で直接ツールを使用できます。以下にいくつかの例を示します：

  • プロジェクトの一覧表示
私のBacklogプロジェクトをすべてリストアップしてください。
  • 新しい課題の作成
PROJECT-KEYプロジェクトに「ログインページのエラーを修正」というタイトルの高優先度のバグ課題を作成してください。
  • プロジェクト詳細の取得
PROJECT-KEYプロジェクトの詳細を表示してください。
  • Gitリポジトリの操作
PROJECT-KEYプロジェクト内のすべてのGitリポジトリをリストアップしてください。
  • プルリクエストの管理
PROJECT-KEYプロジェクトの「repo-name」リポジトリ内のすべてのオープンなプルリクエストを表示してください。

PROJECT-KEYプロジェクトの「repo-name」リポジトリで、ブランチ「feature/new-feature」から「main」への新しいプルリクエストを作成してください。
  • ウォッチアイテム
私がウォッチしているすべてのアイテムを表示してください。

i18n / 説明のオーバーライド

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

ファイルには、ツール名をキーとし、新しい説明を値とするJSONオブジェクトを含める必要があります。 例：

{
  "TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "代替の説明文",
  "TOOL_CREATE_PROJECT_DESCRIPTION": "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-translations フラグを指定してバイナリを実行することで、現在のデフォルト翻訳（オーバーライドを含む）をエクスポートできます。

これにより、行ったカスタマイズを含むすべてのツール説明が標準出力に出力されます。

例：

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

または

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

日本語翻訳テンプレートの使用

サンプルの日本語設定ファイルは次の場所に提供されています：

translationConfig/.backlog-mcp-serverrc.json.example

これを使用するには、ホームディレクトリに .backlog-mcp-serverrc.json としてコピーします：

その後、必要に応じてファイルを編集して説明をカスタマイズできます。

環境変数の使用

または、環境変数を介してツールの説明をオーバーライドすることもできます。

環境変数名は、ツールキーに基づいており、BACKLOG_MCP_ がプレフィックスとして付き、大文字で記述されます。

例： 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": "代替の説明文"
      }
    }
  }
}

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

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

高度な機能

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

次の方法でツール名にプレフィックスを追加します：

--prefix backlog_

または環境変数経由：

PREFIX="backlog_"

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

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

フィールド選択（GraphQLスタイル）

--optimize-response

または環境変数：

OPTIMIZE_RESPONSE=1

次に、特定のフィールドのみを要求します：

get_project(projectIdOrKey: "PROJECT-KEY", fields: "{ name key description }")

AIはフィールド選択を使用してレスポンスを最適化します：

get_project(projectIdOrKey: "PROJECT-KEY", fields: "{ name key description }")

利点：

  • 必要なフィールドのみを要求することでレスポンスサイズを削減
  • 特定のデータポイントに焦点を当てる
  • 大規模なレスポンスのパフォーマンスを向上

トークン制限

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

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

これを変更するには、次を使用します：

MAX_TOKENS=10000

レスポンスが制限を超えた場合、警告と共に切り捨てられます。

注：これはベストエフォートの緩和策であり、保証された強制ではありません。

完全なカスタム設定例

このセクションでは、複数の環境変数を使用した高度な設定を示します。これらは実験的な機能であり、すべての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",
        "ENABLE_DYNAMIC_TOOLSETS": "1"
      }
    }
  }
}

開発

テストの実行

npm test

新しいツールの追加

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

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

サーバーはいくつかのコマンドラインオプションをサポートしています：

  • --export-translations: すべての翻訳キーと値をエクスポート
  • --optimize-response: GraphQLスタイルのフィールド選択を有効にする
  • --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

複数組織対応

このサーバーは、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設定例：

{
  "mcpServers": {
    "backlog": {
      "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組織に対してツールが実行されます。

例：

{
  "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ライセンス のもとでライセンスされています。

注意：このツールはMITライセンスのもとで提供されており、いかなる保証も公式サポートもありません。 内容を確認し、ニーズへの適合性を判断した上で、自己責任で使用してください。 問題が発生した場合は、GitHub Issues を通じて報告してください。