MCP Jira Integration

MCP Jira 連携

Jira 向けのシンプルな Model Context Protocol（MCP）サーバーです。Jira を使用するチームの LLM が、プロジェクトマネージャーやパーソナルアシスタントとして動作できるようにします。Jira REST API v3 上に構築されています。

機能

MCP の主なツール

• create_issue - 適切な書式と ADF の説明を使用して、新しい Jira 課題を作成します
• search_issues - JQL を使用して、スマートな書式設定とページネーションで課題を検索します
• get_sprint_status - メトリクスを含む、包括的なスプリント進捗レポートを取得します
• get_team_workload - チームメンバーの作業負荷とキャパシティを分析します
• generate_standup_report - デイリースタンドアップレポートを自動生成します

プロジェクト管理機能

• 複数プロジェクトのサポート: プロジェクトキーを動的に指定して、複数のプロジェクトを操作できます
• 視覚的なインジケーターによるスプリント進捗の追跡
• チームの作業負荷分析とキャパシティ計画
• デイリースタンドアップレポートの自動生成
• 適切な優先度設定による課題の作成
• 課題のスマートな検索とフィルタリング

信頼性

• レート制限（429）および一時的なエラー（503）の発生時に、指数バックオフによる自動再試行を実行します
• 大量の検索結果に対応するページネーション
• タイムゾーンを考慮した日付の処理
• Jira のカスタムステータスと課題タイプを適切に処理します

必要条件

• Python 3.8 以降
• API トークンを設定した Jira Cloud アカウント
• MCP 対応クライアント（Claude Desktop など）

クイックセットアップ

1. クローンしてインストール:

git clone https://github.com/your-org/mcp-jira.git
cd mcp-jira
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

2. Jira の認証情報を設定:

cp .env.example .env
# Edit .env with your values

JIRA_URL=https://your-domain.atlassian.net
[email protected]
JIRA_API_TOKEN=your_api_token
PROJECT_KEY=PROJ
DEFAULT_BOARD_ID=123

3. サーバーをテスト:

.venv/bin/python -m mcp_jira

出力に Initializing MCP Jira server... と表示されます。停止するには Ctrl+C を押してください。

使用例

課題の作成

「ログインシステムが正常に動作しない問題について、優先度の高いバグを作成して」

• 適切な課題タイプ、優先度、書式を自動で設定します

スプリント管理

「現在のスプリントの状況を教えて」

• メトリクスと視覚的なインジケーターを含む、包括的な進捗レポートを取得します

チーム管理

「john.doe、jane.smith、mike.wilson の作業負荷を表示して」

• キャパシティを分析し、作業負荷の分布を提示します

デイリースタンドアップ

「今日のスタンドアップレポートを生成して」

• 完了済み、進行中、ブロック中の項目を含む書式付きレポートを作成します

MCP 連携

Claude Desktop の場合

設定ファイルの場所:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

リポジトリをクローンした絶対パスに合わせて /path/to/mcp-jira を置き換え、次のエントリを追加してください。

{
  "mcpServers": {
    "mcp-jira": {
      "command": "/path/to/mcp-jira/.venv/bin/python",
      "args": ["-m", "mcp_jira"]
    }
  }
}

注: .venv フォルダー内の Python バイナリを使用してください。これにより、すべての依存関係を利用できます。cwd フィールドは不要です。サーバーは内部で絶対パスを使用して設定を解決します。

正しいパスを確認するには、プロジェクトディレクトリ内で次のコマンドを実行してください。

echo "$(pwd)/.venv/bin/python"

設定を保存した後、Claude Desktop を再起動してください。

その他の MCP クライアントの場合

このサーバーは標準の MCP プロトコルに準拠しており、MCP 対応のあらゆるクライアントで動作します。

設定

必須の環境変数

• JIRA_URL - Jira インスタンスの URL
• JIRA_USERNAME - Jira のユーザー名／メールアドレス
• JIRA_API_TOKEN - Jira の API トークン
• PROJECT_KEY - 操作に使用するデフォルトのプロジェクトキー（リクエストごとに上書きできます）

オプション設定

• DEFAULT_BOARD_ID - スプリント操作に使用するデフォルトのボード（リクエストごとに上書きできます）
• STORY_POINTS_FIELD - ストーリーポイント用のカスタムフィールド ID（デフォルト: customfield_10026）
• DEBUG_MODE - デバッグログを有効にします（デフォルト: false）
• LOG_LEVEL - ログレベル（デフォルト: INFO）

Jira API トークンの取得

1. Atlassian Account Settings に移動します
2. 「Create API token」をクリックします
3. 名前を付けて、トークンをコピーします
4. ユーザー名にメールアドレス、パスワードにトークンを使用します

アーキテクチャ

この実装では、シンプルさと信頼性を優先しています。

• 単一の MCP サーバーファイル - すべてのツールを1か所にまとめています
• 標準の MCP プロトコル - 公式の MCP SDK を使用しています
• Jira REST API v3 - 説明には Atlassian Document Format（ADF）を使用しています
• リッチなフォーマット - 見やすく読みやすいレポートを提供します
• バックオフ付きリトライ - レート制限や一時的な Jira API エラーに自動で対処します
• ページネーション - 大量の課題セットからすべての結果を取得します
• エラー処理 - Jira API の問題やカスタムステータスを適切に処理します
• 非同期処理のサポート - 高速で応答性の高い操作を実現します

トラブルシューティング

よくある問題

1. 「アクティブなスプリントが見つかりません」

   • ボードにアクティブなスプリントがあることを確認してください
   • DEFAULT_BOARD_ID が正しく設定されていることを確認してください

2. 認証エラー

   • API トークンが正しいことを確認してください
   • ユーザー名にメールアドレスを指定していることを確認してください

3. 権限エラー

   • Jira ユーザーに適切なプロジェクト権限があることを確認してください
   • プロジェクトキーが存在し、アクセス権があることを確認してください

デバッグモード

詳細なログを出力するには、.env ファイルで DEBUG_MODE=true を設定してください。

開発

1. リポジトリをフォークします
2. 開発環境をセットアップします：

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

3. テストを実行します：

python -m pytest tests/ -v

4. プルリクエストを送信します

ライセンス

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