JIRA MCP Server

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

機能

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

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

   • 必須パラメータ：projectKey (string)

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

   • 必須パラメータ：issueKey (string)

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

   • 必須パラメータ：issueKey (string)

   • comment (string) または filePath (string) のいずれか — ファイルからコンテンツを編集する を参照

   • オプションパラメータ：commentFormat — plain（デフォルト）、wiki、markdown または adf

4. link-tickets：2つのチケットを「関連あり」の関係でリンクします

   • 必須パラメータ：sourceIssueKey (string)

   • 必須パラメータ：targetIssueKey (string)

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

   • 必須パラメータ：issueKey (string)

   • description (string) または filePath (string) のいずれか — ファイルからコンテンツを編集する を参照

   • オプションパラメータ：descriptionFormat — plain（デフォルト）、wiki、markdown または adf

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

   • 必須パラメータ：parentKey (string)

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

   • 必須パラメータ：parentKey (string)

   • 必須パラメータ：summary (string)

   • オプションパラメータ：description (string) または filePath (string) — ファイルからコンテンツを編集する を参照

   • オプションパラメータ：issueType (string) - サブタスクの課題タイプの名前（例: 'Sub-task'）

Related MCP server: mcp-jira

セットアップ

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": "your-email@example.com",
        "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": "your-email@example.com",
        "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 トークン

   • API トークンは Atlassian アカウント設定 から生成できます。

使用方法

設定後、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 は省略できます：

形式を明示的に渡すと拡張子が上書きされ、他の任意の拡張子のファイルを使用する方法でもあります。パスは絶対パスまたはサーバーの作業ディレクトリからの相対パスです。

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

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

既存コンテンツのパッチ

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

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

エクスポートでは、そのコンテンツを markdown として再アップロードしても安全かどうかが報告されます。Jira はコンテンツを ADF として保存しており、パネル、メンション、ステータスのロゼンジ、メディア、テーブル、タスクリスト、展開などの構造には markdown に相当するものがないため、markdown を再アップロードするとそれらが静かに失われます。これらのいずれかが存在する場合、ツールは警告してリストアップします。代わりに "format": "adf" でエクスポートして 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 を渡すとチェックをスキップして、条件に関係なく上書きします。

開発

サーバーは 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

一般的なワークフロー：

1. jira.ts に変更を加えます

2. 開発中は npm run start:dev を実行するか、コンパイル実行には npm run build の後に npm start を実行します

3. 変更を反映する必要がある場合は MCP クライアントを再起動します

エラー処理

サーバーには次のエラー処理が含まれています：

• 無効な JIRA 資格情報

• アクティブなスプリントがない

• 無効なプロジェクトキーまたは課題キー

• ネットワークエラー

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