JIRA MCP Server

JIRA MCP サーバー

JIRA と連携するためのツールを提供する Model Context Protocol（MCP）サーバーです。MCP インターフェースを通じて、アクティブなスプリントのチケットを取得したり、チケットの詳細情報を取得したりできます。

機能

サーバーは以下のツールを提供します。

1. list-sprint-tickets：指定したプロジェクトのアクティブなスプリントにあるすべてのチケットを取得します

   • 必須パラメーター：projectKey（文字列）

2. get-ticket-details：特定のチケットの詳細情報を取得します

   • 必須パラメーター：issueKey（文字列）

3. add-comment：特定のチケットにコメントを追加します

   • 必須パラメーター：issueKey（文字列）
   • comment（文字列）またはfilePath（文字列）のいずれか — ファイルからのコンテンツ編集を参照してください
   • 任意のパラメーター：commentFormat — plain（デフォルト）、wiki、markdown、またはadf

4. link-issues：すべての外向き課題をすべての内向き課題にリンクします。「外向きが内向きを ブロックする」という意味です

   • 必須パラメーター：outwardIssueKeys、inwardIssueKeys（文字列配列）— linkType: "Blocks"の場合、外向きのキーがブロッカーです
   • 任意のパラメーター：linkType — リンクタイプ名（Blocks、または番号が付与されているサイトでは3. Blocks）、あるいは内向き／外向きの説明です。デフォルトはRelatesです。unlink-issuesでも同じ値を指定できます。
   • 結果は、PROJ-1 blocks PROJ-2のように表記されます

5. update-description：特定のチケットの説明を更新します

   • 必須パラメーター：issueKey（文字列）
   • description（文字列）またはfilePath（文字列）のいずれか — ファイルからのコンテンツ編集を参照してください
   • 任意のパラメーター：descriptionFormat — plain（デフォルト）、wiki、markdown、またはadf

6. list-child-issues：親チケットのすべての子課題を取得します

   • 必須パラメーター：parentKey（文字列）

7. create-sub-ticket：親チケットのサブチケット（子課題）を作成します

   • 必須パラメーター：parentKey（文字列）
   • 必須パラメーター：summary（文字列）
   • 任意のパラメーター：description（文字列）またはfilePath（文字列） — ファイルからのコンテンツ編集を参照してください
   • 任意のパラメーター：issueType（文字列）- サブタスクの課題タイプ名（例：'Sub-task'）

8. add-attachment：ローカルファイルをチケットの添付ファイルとしてアップロードします

   • 必須パラメーター：issueKey（文字列）
   • 必須パラメーター：filePaths（文字列配列）— アップロード前にすべてのパスを検証するため、パスが不正な場合は何もアップロードされません

9. notifications：Atlassian の通知（ベルアイコン）を新しい順に取得します

   • 任意のパラメーター：since / until — ISO 日時（2026-10-01、2026-10-01T09:00:00Z）または現在から遡る期間（30m、24h、7d、2w）
   • 任意のパラメーター：limit（数値）— デフォルトは20、最大100
   • 任意のパラメーター：unreadOnly（ブール値）、category（directまたはwatching）、product（例：jira、confluence）
   • 任意のパラメーター：ids（文字列配列）— 指定した通知のみを返します（各結果のID:行）。他のフィルターとlimitは無視されます
   • 任意のパラメーター：markAsRead（ブール値、デフォルトはfalse）— 返された未読通知を既読にします。そのため、idsとmarkAsReadを組み合わせると、指定した通知だけが既読になります。グループ化された通知はまとめて既読になります。API には通知を削除または非表示にする方法はありません。
   • 通知は Atlassian GraphQL ゲートウェイ（/gateway/api/graphql）から取得します。このゲートウェイでは同じ API トークンを使用できます。フィードはJIRA_HOSTで指定されたサイト向けにリクエストされます（クラウド ID は公開されている/_edge/tenant_infoから取得します）。このルーティングを行わない場合、ゲートウェイから返されるのはプラットフォーム全体の管理者向け通知のみです。

セットアップ

1. 依存関係をインストールします：

   npm install
   

2. TypeScript コードをビルドします：

この手順は、現在 npx の実行に問題がある Windows 版 Cline でのみ必要です。

npm run build

3. Claude アプリの設定ファイルで MCP 設定を行います（通常、macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json にあります）：

Claude の設定：

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["path/to/this/repo/jira.ts"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Cline の設定：

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["path/to/this/repo/dist/jira.js"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

設定

MCP 設定で、次の環境変数を設定する必要があります：

1. JIRA_HOST：Atlassian ドメインの URL（例：https://your-company.atlassian.net）
2. JIRA_EMAIL：JIRA アカウントのメールアドレス
3. JIRA_API_TOKEN：JIRA API トークン
   • Atlassian アカウント設定から API トークンを生成できます。

使用方法

設定が完了したら、Claude の MCP インターフェースからツールを使用できます：

スプリントチケットの一覧表示

プロジェクトのアクティブなスプリントにあるすべてのチケットを取得するには：

<use_mcp_tool>
<server_name>jira</server_name>
<tool_name>list-sprint-tickets</tool_name>
<arguments>
{
  "projectKey": "YOUR_PROJECT_KEY"
}
</arguments>
</use_mcp_tool>

チケットの詳細取得

特定のチケットの詳細情報を取得するには：

<use_mcp_tool>
<server_name>jira</server_name>
<tool_name>get-ticket-details</tool_name>
<arguments>
{
  "issueKey": "PROJECT-123"
}
</arguments>
</use_mcp_tool>

ファイルからのコンテンツ編集

update-description、update-comment、add-comment、create-ticket、create-sub-ticket は、インラインテキストの代わりに filePath を受け付けます。これは長いコンテンツ向けの機能です。元のコンテンツをファイルに保存し、そのファイルを編集して再送信すれば、ツール呼び出しのたびに本文全体を再投稿する必要はありません。2 つの作成ツールでは説明は引き続き省略可能なため、どちらも省略して構いません。

形式は拡張子から判定されるため、descriptionFormat / commentFormat は省略できます：

拡張子	形式	コンテンツ
.md, .markdown	markdown	Markdown（## 見出し、**太字**）
.wiki, .jira	wiki	Jira wiki マークアップ（h2., {code}）
.json, .adf	adf	Atlassian Document Format の生 JSON
.txt, .text	plain	段落で囲まれたプレーンテキスト

形式を明示的に指定すると拡張子より優先されます。これにより、ほかの拡張子のファイルも使用できます。パスは絶対パスか、サーバーの作業ディレクトリからの相対パスを指定します。

{
  "issueKey": "PROJECT-123",
  "filePath": "/abs/path/to/description.md"
}

空のファイルは、既存の説明やコメントを消去しないよう拒否されます。また、インラインテキストと filePath の両方を渡すとエラーになります。

Markdown の構文要素（テーブルのセル（ヘッダーまたは本文）、リスト項目、引用ブロック、フェンス付きコードブロック）が空になる場合は、送信前に有効な ADF に修復されます。Jira のバリデーターは空の tableHeader / tableCell / listItem / blockquote を受け付けず、問題のあるノードではなく フィールド（errors.comment）を示す 400 INVALID_INPUT を返します。そのため、この修復がないと、実際には空のセルが 1 つ原因であるにもかかわらず、コメント全体が拒否されたように見えてしまいます。

既存コンテンツへのパッチ適用

既存の説明やコメントの一部を変更するには、まず export-content でエクスポートし、ファイルを編集して再アップロードします。全体を書き直す必要はありません：

{ "issueKey": "PROJECT-123", "commentId": "54660", "filePath": "/tmp/pir-timeline.md" }

エクスポート結果には、そのコンテンツを Markdown として安全に再アップロードできるかどうかが示されます。Jira はコンテンツを ADF として保存しており、パネル、メンション、ステータスロゼンジ、メディア、テーブル、タスクリスト、展開などの構文には Markdown に相当する表現がありません。Markdown を再アップロードすると、これらは警告なしに削除されます。該当するものがある場合、ツールは警告を表示し、それらを一覧にします。その場合は代わりに "format": "adf" を指定してエクスポートし、JSON にパッチを適用してください。JSON は常に正確に往復変換されます（.json ファイルはアップロード時に ADF として認識されます）。

ファイルに書き込まず、コンテンツをインラインで取得するには filePath を省略してください。コメント ID は get-ticket-details に表示されます。

コンテンツのバージョン（楽観的同時実行制御）

update-description と update-comment では、置き換えるコンテンツが空でない場合、編集の基準となったバージョンを示す expectedVersion が必要です。その後 Jira でコンテンツが変更されていた場合、変更を黙って破棄するのではなく、更新を拒否します。これは、Confluence がページのバージョン番号で実現しているのと同じロックです。

Jira 自体にはバージョン番号がなく、課題の updated タイムスタンプも代わりにはなりません。課題に何らかの変更があるたびに更新されるため、状態遷移、ラベル、新しいコメントが追加されただけでも、競合していない説明のパッチがすべて拒否されてしまいます。そのため、バージョンはコンテンツそのもののハッシュ（v1-…）であり、パッチ対象が変更されたときにのみ変わります。

バージョンは export-content と get-ticket-details から取得できます。get-ticket-details には Description version: と、各コメントの version: が表示されるため、小さなインライン編集のためにエクスポートをやり直す必要はありません。

初めて説明を記述する場合、バージョンは不要です。 expectedVersion を省略すること自体が「ここにはまだ何もありません」という宣言となり、サーバーが確認します。説明がまだ空であれば書き込みは成功し、その間に誰かが説明を書き込んでいた場合は、Jira に現在あるバージョンを示して拒否します。そのため、呼び出し側が空のコンテンツのバージョンを取得しなくても、初回の書き込みもロックで保護されます。

チェックを省略して無条件で上書きするには、"force": true を渡します。

説明とコメントへのファイルの埋め込み

add-comment、update-comment、update-description、create-ticket、create-sub-ticket は、コンテンツ形式の画像構文で参照されているファイルを埋め込みます。

![the error dialog](./screenshots/error.png)

!error.png!          (wiki, image)
[^report.pdf]        (wiki, file)

各参照は課題の添付ファイルに解決されます。Jira はコメント内に表示されるファイルを課題の添付ファイルとして保存するため、コメントと説明は同じ方法で処理されます。参照は次の順序で解決されます。

1. attachment:<filename or ID> は、すでにチケットに添付されているファイルを埋め込みます。
2. ローカルパス（コンテンツファイルからの相対パス、またはインラインテキストの場合はサーバーの作業ディレクトリからの相対パス）のファイルをアップロードします。チケットに同じ名前とサイズの添付ファイルがすでにある場合はそれを再利用するため、編集したファイルを再送信しても同じスクリーンショットが重複して添付されることはありません。
3. それ以外の場合は、同じファイル名の添付ファイルがチケットにあれば、それを使用します。

アップロードや書き込みを行う前に、すべての参照を検証します。無効な参照が1つでもあると、何も変更されずに呼び出しが失敗します。Web URL（https://…）はそのまま残ります。画像はインラインで表示され、その他のファイルは添付ファイルへのリンクとして表示されます。チケット作成時は、課題が存在しないとファイルを添付できないため、課題を作成した後の2段階目で説明を書き込みます。

開発

このサーバーは TypeScript で記述されており、次のものを使用します。

• MCP サーバーの実装には @modelcontextprotocol/sdk
• JIRA API との連携には jira.js

推奨スクリプト：

• ビルド：npm run build
• ビルドと監視：npm run build:watch
• 型チェックのみ：npm run typecheck
• 監視付きで開発実行：npm run start:dev
• コンパイル済みサーバーを実行：npm start
• フォーマットチェック：npm run fmt:check
• フォーマット適用：npm run fmt
• 単体テスト：npm test

npm test は単体テストのみを実行します。テストでは偽の Jira クライアントを使用するため、認証情報は不要で、実際の Jira インスタンスにアクセスすることもありません。チケット、コメント、添付ファイルを作成する実際の Jira 環境でのチェックは、単発スクリプトとして手動で実行し、コミットしません。どちらの種類のテストでも、ホスト名、プロジェクトキー、課題キー、人名、添付ファイル ID など、実際の Jira インスタンスの詳細をコミットしてはいけません。

一般的なワークフロー：

1. jira.ts を変更します。
2. 開発中は npm run start:dev を実行します。コンパイル済みの実行では、npm run build の後に npm start を実行します。
3. 必要に応じて MCP クライアントを再起動し、変更を反映します。

エラー処理

このサーバーには、次のエラーに対する処理が含まれています。

• JIRA 認証情報が無効
• アクティブなスプリントがない
• プロジェクトキーまたは課題キーが無効
• ネットワークエラー

エラーメッセージはツールの応答として返されます。