バックログMCPサーバー

Name: Backlog MCP Server
Author: nulab

MITライセンス建てる最終コミット

Backlog APIと連携するためのモデルコンテキストプロトコル（MCP）サーバー。このサーバーは、Claude Desktop、Cline、CursorなどのAIエージェントを通じて、Backlog内のプロジェクト、課題、Wikiページなどを管理するためのツールを提供します。

特徴

プロジェクト管理（作成、読み取り、更新、削除）
問題追跡（作成、更新、削除、リスト）
Wikiページ管理
Gitリポジトリ管理
プルリクエスト管理（作成、更新、リスト、コメント）
通知管理
ウォッチリスト管理
最適化されたレスポンスのためのGraphQLスタイルのフィールド選択
大規模なレスポンスのトークン制限
強化されたエラー処理
さらにBacklog APIとの統合

Related MCP server: API Tester MCP Server

要件

ドッカー
APIアクセス可能なBacklogアカウント
BacklogアカウントのAPIキー

インストール

オプション1: Docker経由でインストールする

この MCP サーバーを使用する最も簡単な方法は、Claude Desktop または Cline の MCP 構成を使用することです。

Claude DesktopまたはClineの設定を開く
MCP構成セクションに移動する
次の構成を追加します。

{
  "mcpServers": {
    "backlog": {
      "command": "docker",
      "args": [
        "run",
        "-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 キーに置き換えます。

高度な設定オプション

これは実験的なアプローチであり、コンテキストウィンドウのサイズを縮小する標準的な方法ではありません。このMCPをAIエージェントで使用できない場合は、以下の設定を調整してみてください。サーバーの動作をカスタマイズするためのオプションを追加することもできます。

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

MAX_TOKENS : レスポンスで許可されるトークンの最大数（デフォルト: 50000）
OPTIMIZE_RESPONSE : レスポンスサイズを最適化するためにGraphQLスタイルのフィールド選択を有効にする（デフォルト：false）

Dockerイメージを最新の状態に保つ

デフォルトでは、Dockerはローカルにキャッシュされたイメージ（既にプルされている場合）を使用します。ghcr.io ghcr.io/nulab/backlog-mcp-server backlog-mcp-server の最新バージョンを常に使用するには、以下のいずれかの方法を検討してください。

オプション 1: `--pull always`使用する (推奨)

Docker 20.10 以降を使用している場合は、 args配列を変更して--pull alwaysフラグを含めることができます。

{
  "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"
      }
    }
  }
}

これにより、Docker は実行前に常に GitHub Container Registry から最新のイメージをプルするようになります。

オプション2: 最新のイメージを手動で取得する

お使いの Docker バージョンが --pull always をサポートしていない場合は、サーバーを実行する前に最新のイメージを手動でプルできます。

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

オプション2: 手動インストール

リポジトリをクローンします。

git clone https://github.com/nulab/backlog-mcp-server.git
cd backlog-mcp-server

依存関係をインストールします:
```
npm install
```
プロジェクトをビルドします。
```
npm run build
```
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"
      }
    }
  }
}

利用可能なツール

サーバーは、Backlog と対話するための次のツールを提供します。

宇宙ツール

ツール名	説明
`get_space`	バックログスペースに関する情報を返します
`get_users`	Backlogスペース内のユーザーのリストを返します
`get_myself`	認証されたユーザーに関する情報を返します
`get_priorities`	優先順位のリストを返します
`get_resolutions`	問題解決のリストを返します
`get_issue_types`	プロジェクトの問題タイプのリストを返します

プロジェクトツール

ツール名	説明
`get_project_list`	プロジェクトのリストを返します
`add_project`	新しいプロジェクトを作成します
`get_project`	特定のプロジェクトに関する情報を返します
`update_project`	既存のプロジェクトを更新する
`delete_project`	プロジェクトを削除します
`get_custom_fields`	プロジェクトのカスタムフィールドのリストを返します

問題ツール

ツール名	説明
`get_issue`	特定の問題に関する情報を返します
`get_issues`	問題のリストを返します
`count_issues`	問題の数を返す
`add_issue`	指定されたプロジェクトに新しい問題を作成します
`update_issue`	既存の問題を更新します
`delete_issue`	問題を削除します

コメントツール

ツール名	説明
`get_issue_comments`	問題に対するコメントのリストを返します
`add_issue_comment`	問題にコメントを追加する

ウィキツール

ツール名	説明
`get_wiki_pages`	Wikiページのリストを返します
`get_wikis_count`	プロジェクト内のWikiページの数を返します
`get_wiki`	特定のWikiページに関する情報を返します
`add_wiki`	新しいWikiページを作成します

カテゴリツール

ツール名	説明
`get_categories`	プロジェクトのカテゴリのリストを返します

通知ツール

ツール名	説明
`get_notifications`	通知のリストを返します
`count_notifications`	通知の数を返します
`reset_unread_notification_count`	未読通知数をリセット
`mark_notification_as_read`	通知を既読にする

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`	プルリクエストのコメントを更新する

監視ツール

ツール名	説明
`get_watching_list_items`	ユーザーの監視対象アイテムのリストを返します
`get_watching_list_count`	ユーザーのウォッチアイテムの数を返します

使用例

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

プロジェクトの一覧

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

フィールド選択の使用

OPTIMIZE_RESPONSEオプションを有効にすると、GraphQL スタイルの構文を使用して取得するフィールドを指定できます。

Show me the details of the PROJECT-KEY project, but only include the name, key, and description fields

AI はフィールド選択を使用して応答を最適化します。

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

これにより、特に大きなオブジェクトの場合、応答サイズと処理時間が削減されます。

高度な機能

レスポンスの最適化

フィールド選択

OPTIMIZE_RESPONSE=trueで有効にすると、GraphQL スタイルの構文を使用して特定のフィールドを選択できます。

{
  id
  name
  description
  users {
    id
    name
  }
}

これにより、次のことが可能になります。

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

トークン制限

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

デフォルトの制限: 50,000トークン
MAX_TOKENS環境変数で設定可能
制限を超えた応答はメッセージとともに切り捨てられます

i18n / 説明の上書き

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

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

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

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

環境変数（例： BACKLOG_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION ）
.backlog-mcp-serverrc.jsonのエントリ - サポートされている構成ファイル形式: .json、.yaml、.yml
組み込みフォールバック値（英語）

サンプル設定:

{
  "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 フラグを付けてバイナリを実行すると、現在のデフォルトの翻訳 (オーバーライドを含む) をエクスポートできます。

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

例：

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": "An alternative description"
      }
    }
  }
}

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

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

発達

テストの実行

npm test

新しいツールの追加

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

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

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

--export-translations : すべての翻訳キーと値をエクスポートする
--optimize-response : GraphQLスタイルのフィールド選択を有効にする
--max-tokens=NUMBER : レスポンスの最大トークン制限を設定する

例：

node build/index.js --optimize-response --max-tokens=100000

ライセンス

このプロジェクトはMIT ライセンスに基づいてライセンスされています。

注意: このツールは、MIT ライセンスの下で**、いかなる保証や公式サポートもなしに**提供されます。
内容をご確認の上、ご自身のニーズに適しているかどうかを判断した上で、自己責任でご使用ください。
何か問題が発生した場合は、 GitHub Issuesからご報告ください。