JIRA MCP Server (Async)

JIRA MCP サーバー（非同期）

stdio トランスポートを介して JIRA と連携する、非同期の Model Context Protocol（MCP）サーバーです。Atlassian Cloud と Server/DC の両方に対応しています。

MCP ツール

課題のライフサイクル全体を網羅する 6 つのツールと、2 つのプロンプトテンプレートがあります。

ツール	説明	主なパラメーター
jira_search_issues	JQL を使って課題を検索します（ページネーション対応）	jql, max_results, start_at
jira_get_issue	課題の詳細、コメント、リンクを取得します。サブタスクやトランジションも任意で取得できます	issue_key, include_subtasks, include_transitions
jira_create_issue	新しい課題を作成します	project_key, summary, description, issue_type_name
jira_update_issue	既存の課題のフィールドを更新し、任意でコメントを追加します	issue_key, summary, description, assignee, priority, labels, comment
jira_transition_issue	ワークフロートランジションを使って課題を移動します	issue_key, transition_id, comment
jira_get_create_meta	課題の作成前に必須フィールドと許可されている値を取得します	project_key, issue_type

機能

• Cloud + Server/DC：JIRA_USER_EMAIL 環境変数を使ってデプロイメントタイプを自動検出します
• トークンの最適化：API レスポンスを変換し、トークン数を 40～60% 削減します
• ADF 対応：Atlassian Document Format の読み書きに対応します（Cloud v3）
• コネクションプーリング：プールサイズを設定可能な aiohttp を使用します
• レート制限：組み込みのスロットリングと、429 応答時の指数バックオフに対応します
• テスト可能：_set_client() によるクライアントの注入、HTTP レベルテスト用のセッション注入に対応し、ユニットテストを 113 件備えています

セットアップ

前提条件

• Python 3.13+
• uv パッケージマネージャー
• JIRA API トークン

インストール

git clone https://github.com/judexzhu/mcp-jira.git
cd mcp-jira
uv sync
cp config.env.example .env
# Edit .env with your JIRA credentials

環境変数

変数	説明	デフォルト	必須
JIRA_SERVER_URL	JIRA インスタンスの URL	—	はい
JIRA_API_TOKEN	JIRA API トークン	—	はい
JIRA_USER_EMAIL	Cloud Basic Auth 用のメールアドレス（Cloud モードを有効化）	—	Cloud のみ
MAX_CONCURRENT_REQUESTS	最大同時リクエスト数およびレート制限（リクエスト/秒）	2	いいえ
REQUEST_TIMEOUT	HTTP リクエストのタイムアウト（秒）	30	いいえ
CONNECT_TIMEOUT	HTTP 接続のタイムアウト（秒）	10	いいえ
LOG_LEVEL	ログレベル	ERROR	いいえ
LOG_TO_STDOUT	stdout へのログ出力を有効化（MCP stdio が動作しなくなります）	false	いいえ

Claude Desktop

Claude Desktop の MCP 設定に追加します（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）。

{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-jira", "python", "jira_mcp_server.py"],
      "env": {
        "JIRA_SERVER_URL": "https://your-company.atlassian.net",
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_USER_EMAIL": "[email protected]"
      }
    }
  }
}

Claude Code

Claude Code の MCP 設定（.claude/settings.json またはグローバル設定の ~/.claude/settings.json）に追加します。

{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-jira", "python", "jira_mcp_server.py"],
      "env": {
        "JIRA_SERVER_URL": "https://your-company.atlassian.net",
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_USER_EMAIL": "[email protected]"
      }
    }
  }
}

または、CLI から追加します。

claude mcp add jira \
  -e JIRA_SERVER_URL=https://your-company.atlassian.net \
  -e JIRA_API_TOKEN=your_api_token \
  -e [email protected] \
  -- uv run --directory /path/to/mcp-jira python jira_mcp_server.py

別の方法として、-e フラグを省略し、mcp-jira ディレクトリ内の .env ファイルに認証情報を記述できます。load_dotenv() が自動的に読み込みます。

テスト

# Unit tests (no credentials needed)
uv sync --group dev
uv run pytest tests/ -v

アーキテクチャ

中核となるファイルは 2 つです。

• jira_mcp_server.py — 6 つの MCP ツール関数と 2 つのプロンプトテンプレート。それぞれクライアントに処理を委譲する薄いラッパーです
• jira_client.py — JiraClientProtocol を接合部とする AsyncJiraClient。_CloudFormat／_ServerFormat アダプター、認証、コネクションプーリング、レート制限、再試行、レスポンス変換を備えています

Cloud と Server/DC の判別には、JIRA_USER_EMAIL の有無を使用します。その理由については、docs/adr/0001-cloud-detection-via-email.md を参照してください。