MCP JIRA Server

MCP JIRA サーバー

AI ツールにシームレスな JIRA 統合を提供する Model Context Protocol（MCP）サーバーです。リッチな Markdown 形式、自動的な Atlassian Document Format（ADF）への変換、柔軟なフィールド管理により、JIRA の課題を作成・管理できます。

Claude Code でのクイックセットアップ

🚀 AI にセットアップを任せる

次のプロンプトのいずれかをコピーして、AI コーディングアシスタントに貼り付けてください。

セットアップのサポート：

Please help me set up the MCP JIRA Server for Claude Code. 
Read the setup guide at: SETUP_ASSISTANT_PROMPT.md

使用例：

Show me how to use MCP JIRA Server effectively.
Read the usage guide at: USAGE_ASSISTANT_PROMPT.md

⚡ クイックインストール（操作に慣れている方向け）

# Install UV if not already installed:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Configure JIRA settings via web UI:
uvx --from ctf-mcp-jira ctf-mcp-jira-server --ui

# Add to Claude Code:
claude mcp add -t stdio mcp_jira "uvx" -- "--from" "ctf-mcp-jira" "ctf-mcp-jira-server"

その後、Claude Code を再起動してください。詳しい手順は以下をご覧ください。

概要

この MCP サーバーを使用すると、AI アシスタントが JIRA REST API v3 を通じて JIRA インスタンスと直接やり取りできます。Markdown から ADF への変換、フィールドのマッピング、複数サイトの設定といった複雑な処理を担い、最小限のセットアップで、AI ツールから適切に書式設定された JIRA の課題を作成できます。

主なアーキテクチャコンポーネント：

• MCP サーバー：stdio／SSE トランスポートに対応する FastMCP ベースのサーバー
• JIRA クライアント：認証処理を備えた REST API への直接統合
• Markdown コンバーター：Markdown を Atlassian Document Format（ADF）に変換
• 設定システム：柔軟なサイト選択が可能な複数 JIRA サイトの設定
• フィールド管理：標準 JIRA フィールドとカスタム JIRA フィールドの両方に対応

機能

• リッチな Markdown 対応：Markdown の説明を、適切に書式設定された ADF に変換できます。次の要素に対応しています。

  • 見出し、段落、テキスト書式（太字、斜体、インラインコード）
  • シンタックスハイライト付きのフェンス付きコードブロック
  • 箇条書きと番号付きリスト
  • 表や複雑な書式要素

• 柔軟なフィールド管理：

  • 標準フィールド（project、summary、description、issue type）を指定して JIRA の課題を作成・更新できます。
  • 信頼性の高い担当者割り当てに対応しています。メールアドレスを指定すると、サーバーが適切な JIRA accountId を特定します。
  • additional_fields パラメーターで、ラベル、優先度、期限などのカスタムフィールドに対応します。
  • JIRA の構成ごとに利用できないフィールドを適切に処理します。

• 複数サイトの設定：サイトエイリアスを使用して複数の JIRA インスタンスに対応します。設定は config.yaml で行えます。

• 包括的なエラー処理：詳細なエラーメッセージとログを提供します。

• 柔軟なトランスポート：stdio と SSE の両方のトランスポートモードに対応します。

インストール

推奨方法

uvx を使用すると、MCP JIRA Server を永続的にインストールせずに実行できます。

# Install UV if not already installed
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell):
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Configure JIRA settings via web UI:
uvx --from ctf-mcp-jira ctf-mcp-jira-server --ui

# This launches a web interface at http://localhost:8501 for configuration

uvx の利点：

• 永続的なインストールを管理する必要がありません
• 常に新しい分離環境で実行されます
• 利用可能な更新を自動的にダウンロードします
• 「アンインストールして再インストール」する必要がありません

注： uvx は初回使用時にパッケージをダウンロードしてキャッシュします。2 回目以降の実行は速くなりますが、毎回新しい環境が使用されます。

ソースからのインストール（開発用）

# Clone the repository
git clone https://github.com/codingthefuturewithai/mcp_jira.git
cd mcp_jira

# Create and activate a virtual environment using UV
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
uv pip install -e .

インストールのトラブルシューティング

よくある問題：

• 「コマンドが見つかりません」：UV がインストールされ、PATH に設定されていることを確認してください
• ポートがすでに使用されています：UI の起動時に --ui-port 8502（または別のポート）を使用してください
• 接続エラー：uvx は必要に応じてパッケージをダウンロードするため、インターネット接続を確認してください
• 開発では、必ず仮想環境を使用してください

プラットフォーム固有の問題：

• Windows：権限エラーが発生した場合は、PowerShell を管理者として実行してください
• macOS：SSL エラーが発生した場合は、証明書が最新であることを確認してください：brew install ca-certificates
• Linux：追加のシステムパッケージのインストールが必要な場合があります：sudo apt-get install python3-dev

詳しいトラブルシューティングについては、Confluence のドキュメントをご覧ください。

設定

JIRA の設定

サーバーが JIRA インスタンスに接続するには、config.yaml ファイルが必要です。サーバーは次の場所を優先順位の高い順に確認し、このファイルを読み込みます。

1. --config コマンドライン引数で指定されたパス。
2. MCP_JIRA_CONFIG_PATH 環境変数で指定されたパス。
3. OS ごとの既定のユーザー設定ディレクトリ：
   • Linux：~/.config/mcp_jira/config.yaml
   • macOS：~/Library/Application Support/mcp_jira/config.yaml
   • Windows：%APPDATA%\MCPJira\mcp_jira\config.yaml（注：%APPDATA% は通常 C:\Users\<username>\AppData\Roaming に解決されます）

これらの場所のいずれにも設定ファイルが見つからない場合、サーバーは必要なディレクトリ（存在しない場合）と、OS ごとの既定のパスにテンプレートの config.yaml ファイルを自動的に作成します。その後、このテンプレートに実際の JIRA サイトの詳細を記入してください。

記入済みの config.yaml の例：

name: "My Company JIRA Integration"
log_level: "INFO" # Supported levels: DEBUG, INFO, WARNING, ERROR, CRITICAL

default_site_alias: "prod_jira"

sites:
  prod_jira:
    url: "https://mycompany.atlassian.net"
    email: "[email protected]"
    api_token: "abc123xyz789efg_your_token_here_jkl"
    cloud: true

  dev_jira:
    url: "https://dev-mycompany.atlassian.net"
    email: "[email protected]"
    api_token: "another_token_for_dev_environment"
    cloud: true

# Optional: Advanced logging configuration (defaults are usually sufficient)
# log_file_path: "/var/log/custom_mcp_jira/activity.log" # Overrides default log file paths
# log_max_bytes: 20971520  # Max log file size in bytes (e.g., 20MB)
# log_backup_count: 10     # Number of backup log files to keep

JIRA API トークン

1. JIRA インスタンスにログインします。
2. アカウント設定に移動します（通常はアバター／プロフィール画像をクリックします）。
3. セキュリティ > API トークンに移動します（正確な場所は JIRA のバージョンによって多少異なる場合があります）。
4. API トークンを作成をクリックします。
5. トークンにわかりやすいラベル（例：mcp_jira_server_token）を付けます。
6. 生成されたトークンをすぐにコピーします。トークンを再度表示することはできません。
7. コピーしたトークンを config.yaml ファイルに追加します。

設定エディター UI

このプロジェクトには、config.yaml ファイルを簡単に管理できるよう、Streamlit で構築されたウェブベースの設定エディターが含まれています。

機能

• 一般設定（サーバー名、ログレベル、既定のサイトエイリアス）の表示と編集。
• JIRA サイトの設定（エイリアス、URL、メールアドレス、API トークン、クラウドのステータス）の表示、編集、追加、削除。
• 変更内容は、MCP サーバーが使用する config.yaml ファイルに直接保存されます。
• エディターはサーバーと同じ設定ファイルのパス決定ロジック（CLI による上書き、環境変数、または OS ごとの既定値）を自動的に使用します。

エディターの起動

MCP サーバーのコマンドで --ui フラグを使用すると、設定インターフェースを起動できます。

# Using uvx (recommended - no installation required)
uvx --from ctf-mcp-jira ctf-mcp-jira-server --ui

# Or specify a custom port
uvx --from ctf-mcp-jira ctf-mcp-jira-server --ui --ui-port 8502

ブラウザーが開き、http://localhost:8501（または指定したポート）で Streamlit の設定 UI が表示されます。

スクリーンショット

使い方

MCP サーバーの起動

Claude Code と一緒に使用する場合、クイックセットアップに記載されている claude mcp add コマンドによってサーバーが自動的に起動します。手動でのテストやその他の用途では、次のコマンドを使用します。

# Run with stdio transport (default) using uvx
uvx --from ctf-mcp-jira ctf-mcp-jira-server

# Run with SSE transport
uvx --from ctf-mcp-jira ctf-mcp-jira-server --transport sse --port 3001

# Use custom configuration file
uvx --from ctf-mcp-jira ctf-mcp-jira-server --config /path/to/config.yaml

# Launch configuration UI
uvx --from ctf-mcp-jira ctf-mcp-jira-server --ui

注： uvx を使用すると、サーバーは毎回新しい分離環境で実行されるため、依存関係の競合を回避できます。

利用可能なツール

このサーバーは、JIRA と連携するために次のツールを公開しています。

create_jira_issue

新しい JIRA 課題を作成します。プロジェクト、要約、Markdown 形式の詳細な説明（JIRA のリッチテキスト形式に変換されます）、課題タイプ、担当者、その他のカスタムフィールドを指定できます。

update_jira_issue

既存の JIRA 課題を更新します。要約、説明（Markdown に対応）、担当者、課題タイプ、その他のカスタムフィールドなどを変更できます。指定したフィールドのみが変更されます。

search_jira_issues

JQL（JIRA Query Language）構文を使用して、JIRA の課題を検索します。条件に一致する課題を見つけるための JQL クエリを指定してください。

パラメーター：

• query（必須）：課題の検索に使用する JQL クエリ文字列
• site_alias（任意）：複数サイト構成で使用するサイトエイリアス
• basic_only（任意、デフォルト：False）：返される詳細レベルを制御します
  • False（デフォルト）の場合：すべての標準フィールド、課題リンク、リモートリンク、コメント、作業ログを含む包括的な課題データを返します
  • True の場合：パフォーマンス向上のため、キー、要約、説明のみを返します

戻り値：

• 基本モードの場合：課題キー、要約、説明
• 全詳細モードの場合、次の情報を含む課題の詳細：
  • 標準フィールド（プロジェクト、タイプ、ステータス、優先度、担当者、日付）
  • 課題リンク（ブロック、ブロックされている、関連など、他の JIRA 課題との関係）
  • リモートリンク（Web リンク、Confluence ページなど）
  • 作成者とタイムスタンプを含むコメント
  • 時間追跡情報を含む作業ログ

クエリの例：

• project = MYPROJECT
• project = MYPROJECT AND status = 'In Progress'
• assignee = currentUser() AND created >= -7d

使用例：

# Get basic issue information (faster)
search_jira_issues(query="project = ABC", basic_only=True)

# Get comprehensive issue details (default)
search_jira_issues(query="project = ABC AND updated >= -7d")

ロギング

サーバーはアクティビティを stderr とローテーションログファイルの両方に記録します。

ログファイルの場所： ログファイルは、デフォルトで OS ごとに異なる場所に保存されます。

• macOS：~/Library/Logs/mcp_jira/mcp_jira.log
• Linux：
  • root として実行している場合：/var/log/mcp_jira/mcp_jira.log
  • root 以外として実行している場合：~/.local/state/mcp_jira/mcp_jira.log
• Windows：%LOCALAPPDATA%\MCPJira\mcp_jira\Logs\mcp_jira.log（注：通常、%LOCALAPPDATA% は C:\Users\<username>\AppData\Local に解決されます）

設定： ログの動作（レベル、ファイルパス、ローテーション設定）は、config.yaml ファイルで設定します。log_level、log_file_path、log_max_bytes、log_backup_count の詳細については、「Configuration」セクションの config.yaml の例を参照してください。

ログレベルは、MCP_JIRA_LOG_LEVEL 環境変数を使用して上書きすることもできます。この環境変数が設定されている場合、config.yaml の log_level より優先されます。

# Example: Set log level to DEBUG for detailed API communication
MCP_JIRA_LOG_LEVEL=DEBUG mcp_jira-server

有効なログレベル：DEBUG、INFO（指定がない場合のデフォルト）、WARNING、ERROR、CRITICAL。

要件

• Python 3.11 以降（3.13 未満）
• オペレーティングシステム：Linux、macOS、Windows
• JIRA インスタンスへのネットワークアクセス
• 有効な JIRA API トークン

開発

開発環境のセットアップ、MCP Inspector でのテスト、テストの実行、コントリビューションガイドライン、アーキテクチャの概要など、詳しい開発手順については DEVELOPMENT.md を参照してください。

トラブルシューティング

よくある問題

認証エラー

• API トークンが正しく、有効期限が切れていないことを確認してください
• メールアドレスが JIRA アカウントと一致していることを確認してください
• JIRA インスタンスの URL にアクセスできることを確認してください

フィールドエラー

• カスタムフィールドまたは任意のフィールドには additional_fields を使用してください
• JIRA の設定でフィールドが利用可能か確認してください
• サーバーは利用できないフィールドを問題なく無視します

Markdown 変換の問題

• フェンス付きコードブロックが正しい構文を使用していることを確認してください
• 複雑なテーブルは手動で書式を整える必要がある場合があります
• 変換に関する警告がないかログを確認してください

接続の問題

• JIRA インスタンスへのネットワーク接続を確認してください
• ファイアウォール／プロキシの設定を確認してください
• JIRA REST API v3 にアクセスできることを確認してください

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については LICENSE ファイルを参照してください。

作者

AI とともに未来を切り拓く

• GitHub：codingthefuturewithai
• Email：[email protected]