Claude Code用 MCP Jira Server

Claude Codeと統合するための、包括的なJira用Model Context Protocol (MCP) サーバーです。このサーバーは、課題管理、スプリント操作、コメント、添付ファイル、バッチ処理を含む完全なJira機能を提供します。

License: MIT TypeScript Node.js

⚠️ セキュリティ上の注意: APIトークンをコミットしないでください！環境変数（~/.zshrcなど）またはシークレット管理を使用してください。

🚀 機能

📋 課題管理 (12ツール)

create-issue - カスタムフィールドや日付を含むすべてのフィールドをサポートして課題を作成
update-issue - スマートなフィールド処理で既存の課題を更新
get-issue - 詳細な課題情報を取得
search-issues - JQLまたは日付サポート付きの簡略化されたフィルターを使用した高度な検索
transition-issue - ワークフローの状態間で課題を移動
link-issues - 課題間の関係を作成（スマートな型マッチング付き）
get-link-types - 利用可能な課題リンクタイプを一覧表示
get-fields - プロジェクト/課題タイプで利用可能なフィールドを表示
diagnose-fields - フィールド設定のトラブルシューティングとカスタムフィールドIDの検索
create-epic-with-subtasks - 1回の操作で複数のサブタスクを持つエピックを作成
create-task-for-epic - エピックにリンクされたタスクを作成（ローカライズされたJira向けに最適化）

💬 コメントと履歴 (3ツール)

get-comments - 作成者とタイムスタンプ情報を含む課題コメントを読み取り
get-history - フィールド変更を含む詳細な変更履歴を表示
add-comment - Atlassian Document Formatをサポートしてコメントを追加
batch-comment - 複数の課題に同時に同じコメントを追加

📎 添付ファイル (2ツール)

get-attachments - メタデータ（サイズ、タイプ、アップロード日）を含む添付ファイルを一覧表示
upload-attachment - Base64エンコーディングを使用してファイルをアップロード

🏃 スプリントとアジャイル管理 (4ツール)

get-boards - アジャイルプロジェクトで利用可能なJiraボードを一覧表示
get-sprints - ステータスインジケーター付きでボードのスプリントを表示
move-issue-to-sprint - スプリントとバックログ間で課題を移動
create-sprint - 開始日/終了日（オプション）を指定して新しいスプリントを作成

リソース

jira://projects - アクセス可能なすべてのプロジェクトを一覧表示
jira://project/{key} - 特定のプロジェクトの詳細を取得
jira://issue/{key} - 特定の課題の詳細を取得
jira://myself - 現在のユーザー情報
jira://search?jql={query} - 検索結果

プロンプト

standup-report - デイリースタンドアップレポートを生成
sprint-planning - スプリント計画活動を支援
bug-triage - バグの優先順位付けとトリアージを支援
release-notes - 完了した課題からリリースノートを生成
epic-status - 包括的なエピック進捗レポート

インストール

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

git clone https://github.com/tom28881/JIRA_MCP.git
cd JIRA_MCP

依存関係をインストールします:

npm install

プロジェクトをビルドします:

npm run build

環境変数（例: ~/.zshrc）にJiraの認証情報を設定します:

Jira Cloudの場合:

export JIRA_HOST=https://your-company.atlassian.net
export JIRA_EMAIL=your-email@company.com
export JIRA_API_TOKEN=your-api-token

Jira Server/DC 9.12+の場合:

export JIRA_HOST=https://jira.your-company.com
export JIRA_PAT=your-personal-access-token

Jira Server/DC (レガシー) の場合:

export JIRA_HOST=https://jira.your-company.com
export JIRA_USERNAME=your-username
export JIRA_PASSWORD=your-password

完全な認証ガイドについては、docs/AUTH_SETUP.mdを参照してください。

認証情報の取得

Jira Cloud (APIトークン)

Atlassianアカウント設定にログインします
「APIトークンを作成」をクリックします
名前を付けます（例: "MCP Server"）
トークンをコピーし、シェル設定（例: ~/.zshrc）に JIRA_API_TOKEN として追加します

Jira Server/DC 9.12+ (パーソナルアクセストークン)

Jira Server/DCにログインします
プロフィール → パーソナルアクセストークン に移動します
トークンを作成 をクリックします
名前と有効期限（最大365日）を設定します
すぐにトークンをコピーしてください — 再度表示することはできません
シェル設定（例: ~/.zshrc）に JIRA_PAT として追加します

詳細なセットアップ手順については、docs/AUTH_SETUP.mdを参照してください。

Claude Codeの設定

このMCPサーバーをClaude Codeで使用するには、MCP設定で構成する必要があります。

オプション1: 環境変数を使用する（推奨）

シェル設定（例: ~/.zshrc）で環境変数を使用してサーバーを設定します:

# Add to ~/.zshrc
export JIRA_HOST="https://your-company.atlassian.net"
export JIRA_EMAIL="your-email@company.com"
export JIRA_API_TOKEN="your-api-token"
export JIRA_DEFAULT_PROJECT="PROJ"

# Restart terminal or run: source ~/.zshrc
# Then run Claude Code with the MCP server
claude --mcp "node /absolute/path/to/mcp-jira-server/dist/index.js"

オプション2: Claude Code設定に追加する

Claude Code設定ファイル（~/.claude/settings.json）にサーバーを追加します:

{
  "mcpServers": [
    {
      "name": "jira",
      "command": "node",
      "args": ["/absolute/path/to/mcp-jira-server/dist/index.js"],
      "env": {
        "JIRA_HOST": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_DEFAULT_PROJECT": "PROJ"
      }
    }
  ]
}

使用例

課題の作成

Create a new bug in project PROJ with high priority about login issues

Create a story "Implement user authentication" with 5 story points and assign it to john@example.com

日付と時間見積もりの設定

Create task "Database backup" with dueDate "next week" and originalEstimate "4h"

Update PROJ-123 with startDate "tomorrow" and dueDate "+14d"

Create issue "Quarterly review" with dueDate "31.3.2025" and originalEstimate "2 days"

サブタスクを持つエピックの作成

Create an epic "Database Migration" in project PROJ with subtasks "Backup current data" and "Migrate schema"

サブタスクの作成

Create a subtask "Review code" for parent issue PROJ-123

チェコ語Jiraのサポート

Create issue type "Úkol" in project PROJ

Create task for epic PPC-48 with summary "Database backup"

課題の検索

Find all open bugs assigned to me

Search for issues in project PROJ with label "urgent" that are not done

日付ベースの検索

Search issues due before "next week" in project PROJ

Find issues created after "2024-12-01" and updated after "yesterday"

Search for overdue issues: dueBefore "today" and status != "Done"

課題の管理

Update PROJ-123 to add story points 8

Transition PROJ-456 to "In Progress"

Link PROJ-123 to PROJ-456 as "blocks"

注意: エピックとストーリーの関係は、通常の課題リンクではなく epicLink フィールドを使用します:

Update PROJ-456 with epicLink "PROJ-100"  # Links story to epic

プロンプトの使用

Generate a standup report for john@example.com

Help me plan the sprint for project PROJ

Create release notes for version 2.0 in project PROJ

高度な設定

カスタムフィールド

このサーバーは、あらゆるJira設定で動作します:

オプション1: 自動検出（推奨）

環境設定でカスタムフィールドIDを未設定のままにすると、サーバーがフィールド名に基づいて自動的に検出します。

オプション2: 手動設定

自動検出が機能しない場合は、環境（例: ~/.zshrc）でカスタムフィールドIDを設定します:

export JIRA_FIELD_STORY_POINTS=customfield_10001
export JIRA_FIELD_ACCEPTANCE_CRITERIA=customfield_10002
export JIRA_FIELD_EPIC_LINK=customfield_10003

フィールドIDの検索

diagnose-fields ツールを使用して、Jiraインスタンスの正しいフィールドIDを見つけます:

diagnose-fields project:"PROJ" issueType:"Story"

テストチケットの自動作成

ストーリーに対するテストチケットの自動作成を有効にします:

AUTO_CREATE_TEST_TICKETS=true

開発

開発モードでの実行

npm run dev

型チェック

npm run typecheck

Lintチェック

npm run lint

機能

🌍 ローカライゼーションサポート

ローカライズされたJiraインスタンス（チェコ語、英語など）を自動サポート
課題タイプ名はどの言語でも可能（例: "Task", "Úkol", "Aufgabe"）
優先度名はローカライゼーションをサポート（例: "High", "Vysoká", "Hoch"）
チェコ語Jira設定向けの特別なサポート
あらゆるJira言語設定で動作

📅 日付と時間の管理

柔軟な日付入力形式:
- ISO: "2024-12-31"
- ヨーロッパ形式: "31.12.2024" または "31/12/2024"
- 相対形式: "today", "tomorrow", "next week", "+7d", "+2w", "+1m"
- チェコ語: "dnes", "zítra", "příští týden"
時間追跡サポート:
- 見積もり: "2h", "1d 4h", "3 days", "2 hodiny"
- 自動形式変換
日付ベースの検索とフィルタリング

🔄 自動リトライ

サーバーは、失敗したリクエストを指数バックオフ（最大3回）で自動的にリトライします。

📦 堅牢なエラー処理

Jira遷移時の空レスポンス処理
コンテキスト付きの詳細なエラーメッセージ
不足している機能に対する正常な劣化（Graceful degradation）

📝 包括的なログ記録

デバッグログを有効にして詳細情報を表示します:

DEBUG=* claude --mcp "./run.sh"
# or specific to jira-mcp:
DEBUG=jira-mcp claude --mcp "./run.sh"

🔒 接続テスト

サーバーは起動時に接続をテストし、認証に失敗した場合は明確なエラーメッセージを提供します。

📄 Atlassian Document Format

プレーンテキストとMarkdownを、リッチテキストフィールド用のJiraのADF形式に自動変換します。

トラブルシューティング

さまざまなJira設定での作業

このMCPサーバーは、以下に関係なくあらゆるJiraインスタンスで動作するように設計されています:

言語設定（英語、チェコ語、ドイツ語など）
カスタムフィールド設定
プロジェクト固有の設定

ベストプラクティス:

get-fields を使用して、言語で利用可能な課題タイプを確認します
diagnose-fields を使用して、カスタムフィールドIDを見つけます
Jiraの正確な課題タイプ名を使用して課題を作成します

よくある問題

認証失敗
- APIトークンが正しいことを確認してください
- メールアドレスがAtlassianアカウントと一致していることを確認してください
- JiraインスタンスのURLに https:// が含まれていることを確認してください
プロジェクトが見つかりません
- プロジェクトへのアクセス権があることを確認してください
- プロジェクトキーが正しいことを確認してください（大文字と小文字を区別します）
カスタムフィールドが機能しません
- diagnose-fields ツールを使用して、プロジェクトの正しいフィールドIDを見つけます
- get-fields ツールを使用して、利用可能なすべてのフィールドを表示します
- カスタムフィールドIDは通常 customfield_ で始まります
- 一部のフィールドは特定の課題タイプでは利用できない場合があります（例: エピックのラベル）
- エピックリンクのフィールドIDはJiraインスタンスによって異なります
リンクタイプが見つかりません
- get-link-types ツールを使用して、利用可能なリンクタイプを表示します
- リンクタイプはJira APIでは大文字と小文字を区別します
- サーバーは大文字と小文字を区別せずにマッチングを試みます
- エピックとストーリーの関係は、通常の課題リンクではなく epicLink フィールドを使用します
エピックとストーリーのリンクの問題
- プロジェクトと「ストーリー」課題タイプに対して diagnose-fields を実行します
- 環境設定の JIRA_FIELD_EPIC_LINK を正しいフィールドIDで更新します
- 更新後、ターミナルを再起動するか source ~/.zshrc を実行します

デバッグモード

詳細なログ記録のために DEBUG 環境変数を設定します:

DEBUG=* claude --mcp "./run.sh"
# or
DEBUG=jira-mcp claude --mcp "./run.sh"

ログの表示

ログはstderrに出力され、以下が含まれます:

接続ステータス
APIリクエストとレスポンス
コンテキスト付きのエラー詳細
パフォーマンスメトリクス

コントリビューション

開発ガイドラインについては CONTRIBUTING.md を参照してください。

ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください

サポート

問題や機能リクエストについては、GitHubのissueトラッカーを使用してください。