Jira Alerts (JSM Operations)

Jira Alerts MCP

エージェントから、ページングの原因と現在のオンコール担当者を確認できます。

Jira Service Management Operations 向けの MCP サーバーです。Opsgenie に代わるアラート機能を提供しており、ほかの Jira MCP サーバーでは対応していません。

アラートを検索して、メモやアクティビティのタイムラインを読み取れます。アラートの確認、クローズ、注釈の追加、対応者の追加も可能です。また、現在および次のオンコール担当者も確認できます。ツールは 12 個で、そのうち 4 個は書き込み操作です。

デモ

稼働中の JSM サイトに対して、1 回のセッションで 3 つの質問をしています。オンコール担当者は誰か、何が未解決か、そして該当するアラートを確認します。特に最後の回答に注目してください。エージェントは確認が実際に反映されたこと（ack landed 16:38:00.577Z）を確かめており、反映されたと思い込んでいません。これはこのサーバーが代わりに処理することで説明する非同期書き込みの動作です。

クイックスタート

必要なもの： Node ≥ 24 と、JSM Operations が有効になっている Atlassian Cloud サイトです。クローンやビルドは不要です。MCP クライアントが公開済みのパッケージを実行します。

1. cloud id を確認します。 サイトにログインした状態で、次のページを開きます。

https://<your-site>.atlassian.net/_edge/tenant_info

{"cloudId":"..."} という 1 行が返されます。この UUID を JSM_CLOUD_ID に設定します。このエンドポイントを使わない場合は、admin.atlassian.com → Apps → Sites → ご利用のサイトにある URL の /s/ の後の部分からも cloud id を確認できます。

2. API トークンを作成します。 id.atlassian.com で作成してください。

3. サーバーを追加します。

Claude Code：

claude mcp add jira-alerts-mcp \
  --scope user \
  --env JSM_CLOUD_ID='your-cloud-id' \
  --env JSM_EMAIL='[email protected]' \
  --env JSM_API_TOKEN="${JSM_API_TOKEN}" \
  --env JSM_TOOLSETS='all' \
  -- npx -y jira-alerts-mcp

JSM_TOOLSETS=all を指定すると、検証済みのすべてのツールセットが登録されます。responder のデフォルトで登録される 28 個ではなく 82 個のツールが利用可能になり、スケジュール、チーム、メンテナンスウィンドウ、ルーティングが追加されます。まずは絞り込んで始めるには、この行を削除してください。all が利用可能なすべての機能を含むわけではありません。隔離されている 3 つの機能群は、名前を指定して個別に要求する必要があります。各ツールセットの対応範囲と、ツールの数を増やせばよいとは限らない理由については、ツールセットの選び方をご覧ください。

--scope user を指定すると、コマンドを実行したディレクトリだけでなく、アカウント全体にサーバーが登録されます。アラートサーバーはすべてのセッションで使いたいため、この設定が適しています。このフラグを指定しない場合、claude mcp add のスコープはデフォルトで local になり、そのディレクトリでのみサーバーを利用できます。

Claude Desktop： 設定ファイルを手動で開くのではなく、アプリから開いてください。メニューバーの Claude メニュー（ウィンドウ内の設定ではありません）→ Settings → Developer → Edit Config を選択します。ファイルがまだ存在しない場合は、これによって作成されます。

{
  "mcpServers": {
    "jira-alerts-mcp": {
      "command": "npx",
      "args": ["-y", "jira-alerts-mcp"],
      "env": {
        "JSM_CLOUD_ID": "your-cloud-id",
        "JSM_EMAIL": "[email protected]",
        "JSM_API_TOKEN": "your-api-token",
        "JSM_TOOLSETS": "all"
      }
    }
  }
}

mcpServers はトップレベルのキーで、ファイルには設定済みのすべてのサーバーが記載されます。すでに mcpServers ブロックがある場合は、その中に jira-alerts-mcp を別のエントリとして追加してください。上記のブロック全体をファイルに貼り付けると、既存の設定が置き換わります。 次に、Claude Desktop を完全に終了して再起動します。このファイルは起動時にのみ読み込まれるため、ウィンドウを閉じるだけでは終了しません。すると、メッセージ作成欄のコネクターパネルにサーバーが表示されます。

ほとんどの他の MCP クライアントでも、同じ JSON 形式を使えます。ここではスコープを選ぶ必要はありません。claude_desktop_config.json はすでにユーザーごとの設定であり、CLI の --scope user と同じ範囲です。

4. 動作を確認します。 エージェントに、未解決のアラートを一覧表示するよう頼みます。これにより、ID が不要な jsm_list_alerts が実行され、認証情報と、14 個のツールのうち 9 個で共通して使われる read:ops-alert スコープを確認できます。

次に、現在のオンコール担当者を尋ねます。これにより jsm_list_schedules が実行されます。スケジュールには read:ops-config が必要なため、これは別の確認です。アラートは取得できるのにスケジュールで 401 が返る場合でも、トークンに問題はありません。下記の必要なスコープを参照してください。

つまずきやすい点をいくつか紹介します。claude mcp add では、サーバー名はフラグより前の最初の位置引数です。npx の -y はインストール確認をスキップしますが、MCP クライアントには確認に応答する方法がありません。また、zsh では ${VAR} を引用符で囲む必要があります。--scope user を指定せずに追加したサーバーは、追加したディレクトリでのみ動作し、それ以外の場所ではエラーもなく見えなくなります。サーバーが消えたように見える場合は、ほかのことをする前に、別のディレクトリから claude mcp list を実行してください。GUI から起動したセッションでは、トークンを設定ファイル自体の env ブロックに置く必要があります。シェル環境は引き継がれないため、上記の JSON には認証情報が直接記載されています。

Claude Desktop にサーバーがまったく表示されない場合、原因のほとんどは次の 2 つで、どちらも通知されません。

• npx が PATH 上にありません。 GUI アプリはシェルではなくウィンドウマネージャーによって起動されるため、nvm 経由でインストールした Node が認識されないことがよくあります。"command" に which node で確認した絶対パスを指定し、"args" でインストール済みの dist/index.js を指定するか、Node をシステム全体にインストールしてください。見つかった Node のバージョンが 24 より古い場合は、内容のわかるエラーではなく EBADENGINE で失敗します。
• 起動中にサーバーが終了しました。 ハンドシェイクの前に認証情報が検証されるため、クラウド ID やトークンが無効だとサーバーはすぐに終了します。標準出力はプロトコル用のチャネルであるため、このメッセージは標準エラー出力にのみ書き込まれます。Claude Desktop では、~/Library/Logs/Claude/mcp-server-jira-alerts-mcp.log（Windows の場合は %APPDATA%\Claude\logs\）にログが保存されます。ログ名は mcpServers で使用したキーに基づきます。Startup failed: を探してください。何が問題なのかが正確に記載されています。

git clone https://github.com/rrvrs/jira-alerts-mcp.git
cd jira-alerts-mcp
npm install
npm run build

  -- node /absolute/path/to/jira-alerts-mcp/dist/index.js

設定

認証情報は起動時に検証されるため、設定に誤りがあると、最初のツール呼び出し時ではなく、その場で対処方法を示すメッセージとともに失敗します。

.env.exampleに、参考用としてこれらの項目を記載しています。サーバー自体は .env を読み込みません。MCP サーバーはクライアントによって起動され、環境変数はクライアントが管理するためです。このファイルをクライアントの env ブロックのチェックリストとして使うか、ローカル開発では set -a; source .env; set +a を実行してください。

認証情報でできること、できないこと

2 つの認証方式は同等ではありませんが、その違いは Atlassian のドキュメントに記載されていません。2026-09-05 に稼働中のテナントで検証しました。

削除スコープは認証方式ごとではなく、トークンごとに付与されます。 同じアカウントの Atlassian アカウント API トークンでも、挙動は異なります。一方はすべての DELETE リクエストで 401 Unauthorized; scope does not match が返されました（認証情報は有効ですが、許可が不足しています）。もう一方は一連の削除をすべて完了しました。そのため、削除時に 401 が返っても、JSM_EMAIL + JSM_API_TOKEN を使うのをやめる必要はありません。削除スコープを含めてトークンを再発行するか、delete:ops-alert:jira-service-management が付与された 3LO または Forge OAuth トークンを JSM_OAUTH_TOKEN として指定してください。401 ハンドラーはこの内容をそのまま示すため、モデルは再試行せずに報告します。

削除を伴うアラートツールは、jsm_delete_alert · jsm_delete_alert_note · jsm_remove_alert_tags · jsm_remove_alert_extra_properties · jsm_delete_alert_attachment です。

アラートの添付ファイルエンドポイントには、二重の制限があります。 API 自体の OpenAPI ドキュメントでは、これらに OAuth スコープが一切割り当てられていません。そのため、削除スコープがないトークンはゲートウェイで scope does not match だけを返されます。これは認証で解決できないように見えますが、実際はそうではありません。必要なスコープをすべて備えたトークンで API に到達すると、代わりに Feature not available in your plan と返されます。プランに添付ファイルが含まれないサイトでは、どのトークンを使っても利用できません。そのため、添付ファイルツールは現在、どのプロファイルにも読み込まれない、隔離された専用の attachments ツールセットに含まれています。ハンドラーは、トークンのスコープを広げるよう促すのではなく、プラン上の制限として報告します。

一部の操作はスコープではなく、JSM のプランに依存します。 Standard テナントでは、スヌーズ、割り当て、カスタムアクションは受け付けられた後、非同期で Your account plan does not support … というエラーになります。リクエストの形式に問題はなく、制限となっているのはプランです。これが書き込み操作が非同期である理由であり、jsm_get_request_status が重要な理由でもあります。これら 3 つの操作では、即時応答はいずれも成功を示す受付結果になります。

検証済みの内容と未検証の内容

このサーバーのすべてのツールは、リリース前に稼働中の Jira Service Management サイトで実行されました。プロファイルで読み込めるすべてのツールが、実際に成功しました。これは不変条件であり、テストで強制されています。未検証とマークされたツールセットは、プロファイルに含められません。

3つのファミリーは検証できませんでしたが、削除するのではなく隔離した状態で同梱しています。これらに問題があると分かっているわけではありません。利用できたサイトではテストできませんでしたが、ブロックされていないサイトであれば、コードはほぼ確実に正しく動作します。

有効にするには、使いたい他のツールセットと一緒に名前を指定します。

"env": { "JSM_TOOLSETS": "all,heartbeats" }

jsm_list_capabilities は実行時に同じ情報を返すため、「ハートビートを作成できますか？」と尋ねるアシスタントには、このファミリーが存在すること、無効になっていること、有効にする方法、そして動作確認されたことがないことが伝わります。推測で答えることはありません。

2つのファミリーは隔離するのではなく、2.0.0 で削除しました。 アラートポリシー（11個のツール）とカスタムユーザーロール（6個のツール）は、2つの別々の認証情報で 403 You are not authorized を返しました。そのうち1つは Jira の ADMINISTER 権限を持っていました。カスタムユーザーロールは Opsgenie の Enterprise 機能で、ポリシーの拒否も同様の制限によるものと思われます。コンパイルできることしか確認できていない17個のツールを、ツール一覧に加える価値はなかったため、削除しました。これらが動作するサイトをお持ちで、再追加を希望する場合は、イシューを作成してください。コードは履歴に残っており、ドリフトガードも引き続きエンドポイントを把握しています。

ツールセットの選択

JSM Operations API には約240の操作があります。すべてを登録すると、クライアントが正確に選択できないツール一覧を渡すことになるため、機能を名前付きのツールセットに分けています。必要なものを選択してください。

さらに3つが同梱されていますが、どのプロファイルでも読み込まれません。検証済みの内容と未検証の内容を参照してください。

さらに、上記をまとめたプロファイルが4つあります。

"env": { "JSM_TOOLSETS": "responder" }     // or "alerts,oncall", or "all"

名前は自由に組み合わせられ、--toolsets=a,bと--read-onlyフラグは環境変数の設定より優先されます。上記の表にない名前を指定すると、起動時に有効な名前と候補が表示され、サーバーは停止します。入力ミスによって、要求した数より少ないツールが知らないうちに使われることはありません。

coreは名前の固定リストであり、ツールセットが導入される前にこのサーバーが提供していた機能を表します。13個のツールを個別に列挙せずに、まさにその構成を求められるように用意されています。他のツールセットと組み合わせても、この14個はそのまま維持されます。core,schedulesはcoreにすべてのスケジュールツールを加えたものであり、両方のファミリーを制限なしで提供するわけではありません。そのため、隣にツールセットを追加しても、core自体が提供する範囲は広がりません。responderはツールセットから構成され、ファミリーが追加されるにつれて範囲が広がります。そのため、これがデフォルトです。アラート用サーバーなのに、再設定するまでアラートツールの大半が見えないのでは、あまり役に立ちません。

allが意味するのは、すべてのツールセットではなく、検証済みのすべてのツールセットです。 隔離されている3つのファミリーは、個別に名前を指定する必要があります（JSM_TOOLSETS=all,heartbeats）。すべてを要求した結果、動作確認されていないツールが提供されることはありません。

jsm_list_capabilitiesは、何を選択しても常に登録されます。 すべてのツールセットと、その読み込み状況、必要なスコープ、変更する環境変数を報告します。そのため、現在の選択範囲にない機能を要求した場合でも、「このサーバーではできません」ではなく、「それはoncallツールセットにあります」とわかります。JSM_TOOLSETSを変更するには再起動が必要です。会話の途中でツールセットを有効にすることはできません。

必須スコープ。 アラートとオンコールには異なるスコープが設定されており、これが設定ミスの最も一般的な原因です。

トークンを発行する前に知っておきたい、3つの重要な点があります。

• 書き込みにも読み取りスコープが必要です。 write:ops-alert:jira-service-managementのみを持つトークンでは失敗します。Atlassianでは、すべての書き込みエンドポイントで読み取りスコープも併せて必要とします。

• ops-configは別途許可が必要で、これがない場合は403ではなく401が返されます。 これを含めない場合、9個のアラートツールは問題なく動作する一方、4個のオンコールツールは失敗します。これは認証情報の問題のように見えますが、そうではありません。読み取りスコープのみを付与する構成と、ops-alertのみを付与する構成は、どちらもサポートされています。エージェントがアクセスできる範囲を意図的に絞る方法です。

• Jiraユーザースコープは任意であり、未設定でもそのことが明確にわかります。 Operations APIが返すレスポンダーはすべて、アカウントIDのみ（712020:9ae5385e-…）です。read:jira-userがあれば、オンコールツールは同じ呼び出し内でIDを名前とメールアドレスに変換します。なくても応答は返されます。IDに加え、名前への変換に必要なスコープを示す行が1つ表示されます。オンコール担当者の表示名より、誰が担当なのかを把握することのほうが重要なので、このスコープがないことでエラーになることはありません。

  read:user:jiraではなく、read:jira-userを使用してください。細粒度スキームでもこれらのエンドポイントをカバーできますが、必要なのはread:application-role:jira + read:group:jira + read:user:jira + read:avatar:jiraをすべて含むセットです。read:user:jiraだけでは不十分であり、AtlassianはこのAPIに対する細粒度スキーム全体を、現在もベータ版としています。 チームの可視性。 アカウントには、該当するチームへの JSM Operations アクセスも必要です。アラートとスケジュールはチームの Operations ページに紐づいているため、チームを参照できない認証情報を使うと、エラーではなく空のリストが返されます。

例

オンコール担当者を尋ねると、jsm_list_schedules に続いて jsm_get_on_call が呼び出されます。

you — payments の現在のオンコール担当者は誰ですか？

# Currently on-call for Payments — Primary

- Dana Okafor

アラートを確認済みにすると、更新されたアラートではなく受領確認が返されます。JSM はアラートのアクションを帯域外で適用するためです。

you — アラート 4f2a9c1e-…-1718395200000 を確認済みにして。対応中です

Acknowledge request accepted for alert `4f2a9c1e-…-1718395200000`.

- **Request id**: `c7b41f30-…`
- **Result**: Request will be processed

JSM applies alert actions asynchronously, so the alert may not reflect this
change immediately. Confirm with jsm_get_request_status using the request id
above, or re-read the alert after a moment.

最後の段落が重要です。これがないと、エージェントはアラートを再読み込みし、まだ未確認だと判断して、もう一度確認済みにしてしまいます。

ツール

10 個のツールセットに 95 個のツールがあります。ツールセットは alerts、alert-actions、oncall、schedules、teams、maintenance、routing、heartbeats、attachments、forwarding です。最初の 3 つはデフォルトで登録され、残りは JSM_TOOLSETS で指定した場合にのみ読み込まれます。また、jsm_list_capabilities を使うと、このインストールで実際に利用できるツールセットが実行時にわかります。

TOOLS.md はカタログです。各ツールの背後にあるエンドポイント、読み取りか書き込みか、破壊的としてマークされているもの、各ファミリーに関する注意事項を記載しています。

JSM_TOOLSETS または JSM_READ_ONLY を使ってツールの範囲を絞れます。ツールセットの選択を参照してください。

このサーバーが処理すること

3 つの API の動作が、単純な統合を気づかれないまま破綻させます。それぞれ、モデルが実際に参照するツールの説明に記載されています。

1. 書き込みは非同期です。 変更を伴うすべてのエンドポイントは、{ result, requestId, took } をただちに返し、変更を帯域外で適用します。確認済みにした直後にアラートを再読み込みしても、まだ未確認と表示されることがよくあります。正しい確認方法は jsm_get_request_status で、各書き込みツールからこの方法を参照できます。

2. tinyId は ID ではありません。 JSM の UI に表示される短い番号（#4821）は /v1/alerts/{id} では拒否されます。このエンドポイントで受け付けるのは、完全な uuid-timestamp 形式の ID のみです。エイリアスには、まったく別のエンドポイント（/v1/alerts/alias?alias=）が必要です。スキーマの説明と 404 ハンドラーの両方にその旨が明記されているため、モデルは同じ呼び出しを再試行せず、自ら修正できます。

3. 検索ウィンドウの上限は 20,000 です。 offset + limit はこの値未満にする必要があります。jsm_list_alerts は、より深いページングをローカルで拒否し、クエリを絞り込むようモデルに伝えるメッセージを返します。これにより、必ず 400 になるリクエストで余分な往復が発生するのを防ぎます。

4. アラートアクションでは、実行者やメモを指定できません。 Opsgenie では確認やクローズの際に user、source、note を指定できました。また、JSM Operations は Opsgenie を再ホストしたものですが、これらのエンドポイントではリクエストボディが宣言されておらず、指定したフィールドは黙って破棄されます。メモ付きで確認してからアクティビティログを読み返しても、メモも実行者も記録されていません。そのため、これらのツールでは該当するパラメーターを提供していません。拒否された引数ならモデルはその事実に基づいて処理できますが、無視された引数は、記録されたはずの判断が実際には失われたように見えてしまいます。永続的なメモを残すには、jsm_add_alert_note を呼び出してください。jsm_create_alert では note と source を指定できます。CreateAlertRequest で両方が宣言されており、API がそれらを受け付けることも確認済みです。

このプロジェクトの目的

アラートは作業項目ではありません。 アラートは別の API /jsm/ops/api（再ホストされた Opsgenie の API）を使用し、独自のスコープ、ID 形式、非同期の書き込み仕様を持っています。MCP Registry には Jira サーバーが 30 個登録されていますが、いずれも作業項目を扱うものです。現在、何がページングを発生させているかを知らせてくれるものはありません。atlassian/atlassian-mcp-server はこのギャップを縮めますが、解消はしません。2026 年 2 月以降、JSM Operations のツールが 4 つ提供されています。getJsmOpsAlerts、getJsmOpsScheduleInfo、getJsmOpsTeamInfo、updateJsmOpsAlert です。しかし、機能は大まかで、updateJsmOpsAlert は確認、確認解除、クローズ、エスカレーションをまとめて扱い、ノート、ログ、タグ、添付ファイル、スヌーズ、割り当て、リクエストのステータス、タイムライン、ローテーション、オーバーライド、ハートビート、メンテナンス、ルーティング、インテグレーション、監査ログには対応していません。また、これらのツールは同リポジトリの README には掲載されておらず、Atlassian のサポート対象ツールのページにのみ記載されています。提供開始時は API トークンのみ対応していたため、OAuth でインストールした場合は利用できません。ホスト型のクローズドなサーバーであるため、こうしたギャップを解消するのは Atlassian であり、コントリビューションで修正できるものではありません。

既存の Opsgenie MCP サーバーは、提供終了が決まっている API を使用しています。 giantswarm/mcp-opsgenie、 burakdirin/opsgenie-mcp-server、 daviddykeuk/opsgenie-mcp は、いずれも GenieKey を使って api.opsgenie.com を呼び出します。Opsgenie は2025 年 6 月 4 日に販売を終了し、2027 年 4 月 5 日にサービスを停止します。その時点で、これらの REST API は応答しなくなります。このサーバーは、それらを置き換える API、https://api.atlassian.com/jsm/ops/api/{cloudId}/v1 を対象としています。

互換性。 JSM Operations を利用している Atlassian Cloud テナントが対象です。スタンドアロンの Opsgenie からすでに移行したサイト、または統合後にプロビジョニングされたサイトが該当します。チームが現在も app.opsgenie.com にログインし、GenieKey で認証している場合、このサーバーではデータにアクセスできません。2027 年までは、上記の Opsgenie サーバーのいずれかでアクセスできます。

プロジェクト構成

src/
├── index.ts                 # transports and startup credential validation
├── server.ts                # assembles the catalogue from the eight families
├── toolsets.ts              # toolsets, profiles, and selection resolution
├── constants.ts             # API root, limits
├── types.ts                 # JSM API interfaces
├── schemas/common.ts        # Zod fragments shared across families
├── services/
│   ├── client.ts            # auth, request, envelope normalisation, error mapping
│   ├── directory.ts         # resolves bare Atlassian ids to names
│   ├── name-cache.ts        # one registry for every process-wide cache
│   ├── format.ts            # markdown rendering, truncation, result envelopes
│   └── render/              # per-family renderers
└── tools/
    ├── define.ts            # defineTool() + registerTools()
    ├── family.ts            # the resource-family factory
    ├── execute-write.ts     # the shared write executor
    ├── list-executor.ts     # the shared list pipeline
    ├── paging.ts            # the paging dialects each endpoint wants
    ├── capabilities.ts      # jsm_list_capabilities
    ├── test-support.ts      # stub client and in-memory MCP harness
    ├── alerts/              # alert reads
    ├── actions/             # alert writes
    ├── oncall/              # who is on call now and next
    ├── schedules/           # schedules, rotations, overrides
    ├── teams/               # teams, roles, contact methods
    ├── maintenance/         # maintenance windows
    ├── heartbeats/          # heartbeat monitors
    └── routing/             # escalations, routing, notification, forwarding rules

アラートの各ファミリーは、ツールごとにファイルを分けています。各モジュールは入力形式、説明、ハンドラーを持ち、それ以外は含みません。一方、設定ファミリーは生成されます。family.ts が ResourceConfig から一覧表示、取得、作成、更新、削除の各形式を機械的に構築します。こうした形式を 10 個手作業で書くと、違いがそれぞれ 3 行しかないファイルが 100 個できてしまうためです。エンドポイントがこの 5 つの形式に当てはまらない場合は、手書きのツールを生成されたツールと並べて配置します。teams/contacts.ts には両方があります。

server.ts は 8 つのファミリーを結合して、完全なカタログである allTools を作成します。toolsets.ts は、プロセスが実際に登録するツールだけに絞り込みます。index.ts が扱うのはトランスポートのみです。全ツールをファミリー別にまとめたツールカタログは、TOOLS.md にあります。

ここにある規約のうち、特に重要なものは 3 つあります。誤って変更すると、サーバーが微妙に壊れる可能性が最も高いものです。それぞれの規約と、その背景にある不具合については、維持すべき規約に記載されています。

コントリビューション

開発の進め方、維持すべき規約、ツールの追加方法については、CONTRIBUTING.md をご覧ください。Issue や PR にクラウド ID、トークン、実際のアラートデータを含めないでください。

セキュリティ

このサーバーは Atlassian の認証情報を保持します。また、HTTP トランスポート自体は認証を行いません。脅威モデル、セキュリティ強化に関する注意事項、脆弱性を非公開で報告する方法については、SECURITY.md をご覧ください。

ライセンス

Apache-2.0