Backlog Remote MCP Server

Backlog 用のリモート MCP (Model Context Protocol) サーバー。 Cloudflare Workers または AWS のどちらにもデプロイできます。

英語 | 日本語

特徴

• マルチスペース — 1 つのサーバーで複数の Backlog スペースを提供

• 読み取り専用ガード — 共有スペースを readOnly にすることで、すべての書き込み API 呼び出しを拒否

• OAuth 2.1 + PKCE — Dynamic Client Registration (DCR) に対応しており、MCP クライアントが直接接続可能

• メール許可リスト — サーバーを利用できるユーザーを制限

• 2 つのランタイム — 同じビジネスロジックが Cloudflare または AWS で動作

Related MCP server: backlog-mcp-server

デプロイ先の選択

ツールとその動作は両方で同じです。

推定コスト

注記 これらは参考値です。 実際の費用はリージョン、利用状況、料金の変更によって変動します。実際の見積りには公式の計算ツールをご利用ください。

• Cloudflare Zero Trust プライシング

• Cloudflare Workers プライシング

• AWS 料金計算ツール

前提条件

個人利用または小規模なチームを想定しています。

固定費用 (アイドル状態でも発生)

AWS では固定コストは実質的に Secrets Manager のみです。 Secrets Manager は使用の有無にかかわらず、シークレットごとに毎月請求されます。Cloudflare では Workers Secrets が無料のため固定コストはありません。

メーター制の費用

想定されるボリューム (月約 3,000 リクエスト) では、どちらも無料の許容範囲内に収まります。API Gateway HTTP API には恒久的な無料枠がないため、AWS では リクエスト数に比例した少額 (100 万リクエストあたり約 $1) が発生します。

知っておくべきしきい値

Cloudflare — Zero Trust の 50 ユーザーライン

Zero Trust (Access) は ユーザー 50 人まで無料です。それを超えると有料プランに移行し、ユーザーごと・月ごとに請求されます。これは支払金額がユーザー数に比例します。

Cloudflare — Workers 無料版の制限

このプロジェクトでは SQLite バックアップ Durable Objects を利用しており、これは Workers 無料プランで利用可能 です。無料プランでは1日あたりのリクエスト数やその他の使用量に制限があり、上限を超過するとエラーが発生します。継続的な利用には. Workers Paid (月額 $5 から) をご検討ください。

AWS — Lambda の恒常的な無料枠

Lambda には月間 100 万リクエストと 400,000GB 秒の無料枠が含まれます。API Gateway と Secrets Manager には恒久的な無料枠はありません。

AWS — CloudWatch Logs

ログはがイレストの量に応じて課金されます。テンプレートは LogRetentionDays (既定 30 日) で保存期間を設定し、ログが際限なく累積しないようにしています。

まとめ

小規模な小チームでは Cloudflare が低額で固定コストがありません。 AWS では Secrets Manager の固定コストが発生しますが、既存の AWS 環境へ統合したり、「IAM」によるアクセス管理を検討している場合は、その旨を考慮して決めてください。

セットアップ

0. 前提条件

Node.js 20 以降。

git clone <this-repo>
cd backlog-remote-mcp-server
npm install

追加のツールはデプロイターゲットによって異なります。

実行順序

1. Backlog API キーとスペース設定 — 両プラットフォーム共通

2. ID プロバイダを選択

   • Google Cloud

   • Microsoft Entra ID

3. デプロイターゲットを選択

   • Cloudflare Workers

   • AWS

問題が発生した場合

トラブルシューティングの節は、各デプロイガイドの末尾にあります。

• Cloudflare

• AWS

アーキテクチャ

MCP client (Claude, Kiro, Cursor, ...)
    ↓ Streamable HTTP + OAuth
Runtime (Cloudflare Workers or AWS Lambda)
    ↓ Upstream IdP (Cloudflare Access or Amazon Cognito)
    ↓ Email allowlist check
    ↓ Backlog API key routing
Backlog space A / B / C ...

ディレクトリ構成

ビジネスロジックはランタイムコードから分離されています。

src/
  core/                    Runtime-independent
    backlog-client.ts      Backlog API client (including the readOnly guard)
    tools/                 40 MCP tools
    create-server.ts       MCP server assembly and authorization
  platforms/
    cloudflare/            Cloudflare Workers wiring
    aws/                   AWS Lambda wiring
infra/
  aws/                     SAM template and parameters

src/core は @modelcontextprotocol/sdk と zod にのみ依存し、ランタイム固有の API を参照しません。プラットフォームを追加するには、src/platforms/ 以下にアダプターを追加すれば、同じツール実装を共有できます。

MCP クライアントから接続

Claude Desktop / Kiro / Cursor (mcp-remote 経由)

{
  "mcpServers": {
    "backlog": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<MCP_HOSTNAME>/mcp"
      ]
    }
  }
}

初回の接続時に、ブラウザウィンドウが開いて認証されます。

MCP Inspector (テスト用)

npx @modelcontextprotocol/inspector@latest

https://<MCP_HOSTNAME>/mcp を inspector に入力し、OAuth 設定を完了します。

使用法

スペースの指定

すべてのツールはオプションの space パラメータを受け付けます。

# Use default space
"Show me the issues for PROJECT-KEY"

# Specify a particular space
"List projects in the PERSONAL space"
→ space: "PERSONAL"

例

# List configured spaces
"What Backlog spaces are available?" → list_spaces

# List projects
"Show COMPANY_A projects" → get_project_list(space: "COMPANY_A")

# Create an issue
"Create a new bug issue in PROJECT-KEY" → add_issue(...)

# List pull requests
"Show open PRs in repo-name" → get_pull_requests(...)

利用可能なツール

add_*、update_*、delete_* は書き込み操作です。readOnly が true に設定されたスペースに対して呼び出すと、Backlog API にリクエストを送る前に拒否されます。list_spaces で各スペースの readOnly 状態を確認できます。

セキュリティ

• 認証: Cloudflare Access → Google / Microsoft Entra ID。OAuth フロー全体を Cloudflare が管理します

• 承認: ALLOWED_EMAILS でアプリケーション層のメール許可リストを提供します

• ダブルチェック: アクセスポリシー (Cloudflare 側) + アプリ内の許可リスト (Worker 側)

• API キーの保護: Backlog の API キーは Cloudflare, ≪≫に保存され、クライアントに公開されません

• PKCE + CSRF : OAuth フローは PKCE (S256) と CSRF トークンで保護されています

• クライアント同意: Dynamic Client Registration は誰でも開かれているため、認可はクライアントとリダイレクト先を示し、CSRF で保護された同意画面で制御されます。承認は client_id と redirect_uri をキーとして行われるため、異なるリダイレクト先での再登録では既存の承認を引き継ぐことはできません

• 書き込みガード: readOnly: true のスペースは、GET 以外のすべての呼び出しを拒否します。チェックは src/core/backlog-client.ts の API 呼び出し層にあり、個々のツール実装には依存しません

• 設定の隔離: すべての環境固有値を .dev.vars (非追跡) に格納します。リポジトリにはプレースホルダのみ含まれます

運営上の留意点

• ALLOWED_EMAILS はこのサーバーでの実質的な承認境界となります。Worker 前面にはゾーンレベルでの Access アプリケーションはありません

• npm run deploy は .dev.vars の値を本番シークレットに上書きします。ローカルと本番で値が異なる場合は、通常のデプロイには deploy:no-secrets を使い、シークレットは secrets:push で明示的に更新します

• Backlog の API キーは、その所有者の完全な権限を持ちます。書き込み不要なスペースには、読み取り専用のキーを発行し、かつ readOnly: true を設定してください

ローカル開発

ローカル実行には Cloudflare Workers ビルド (wrangler dev) を使用します。ビジネスロジックは src/core に存在するため、ここで検証した内容は AWS デプロイでも同様です。

cp .dev.vars.example .dev.vars   # fill in your values
npm run dev
# Server starts at http://localhost:8788/mcp

wrangler dev はローカルで KV と Durable Objects をエミュレートするため、実際の Cloudflare リソースには一切触れません。

設定の確認

完全な OAuth からツール呼び出し (tool call) までを 1 コマンドで確認するには:

npm run check:local

これにより以下の操作が実行され、途中でブラウが開きログインできます。

1. 認証サーバーのメタデータを取得する

2. 動的クライアント登録

3. ブラウザで承認 → IdP ログイン

4. PKCE でのトークン交換

5. initialize / tools/list

6. get_space を呼び出し、Backlog から実際のレスポンスを表示する

tools/list が access_denied のみを返す場合、ログインに使用したメールは許可リストに含まれていません。

デプロイ済みエンドポイントでも動作します。

npm run check:local -- --base https://your-deployed-host

HTTPS 経由での実行

IdP が http:// リダイレクト URL を受け入れない場合に使用します。

npm run dev:https
# Server starts at https://localhost:8788/mcp (self-signed certificate)

型チェックとテスト

型はプラットフォームごとに分離されているため、AWS コードで Workers グローバルを誤って使用する（またはその逆）と型エラーになります。

npm run type-check   # both tsconfig.cloudflare.json and tsconfig.aws.json
npm test             # runs all suites below

いずれも外部サービスにはアクセスしません。DynamoDB と接続先 IdP はスタブされます。

設定ファイル

各ファイルへの入力方法の詳細は、デプロイガイドを参照してください。

ライセンス

MIT