jira-admin-mcp

Jira Admin MCP サーバー

AI アシスタント（Claude、Cursor、VS Code、その他の MCP クライアント）に、Jira Cloud サイトを管理するための専用ツール78個を提供するModel Context Protocolサーバーです。チケットの読み取りや作成だけでなく、カスタムフィールドとその表示場所、権限スキーム、ワークフロー、画面、課題タイプスキーム、グループ、プロジェクトロール、保存済みフィルター、一括操作など、舞台裏の管理作業にも対応します。

多くの Jira MCP サーバーが日常的な利用を対象とするのに対し、このサーバーは管理作業に対応し、安全策（ドライランモード、共有スキームの検出、グループ変更前の本人確認、対処可能なエラー）も備えているため、エージェントが実際の管理タスクを最初から最後まで実行できます。

FastMCPで構築されています。独自の Atlassian メールアドレスと API トークンを使って、Jira Cloud REST API v3 に接続します。

---

クイックスタート

前提条件は2つだけで、どちらも初回に一度準備すればすぐに完了します。

1. Atlassian API トークン（Jira の権限が引き継がれるため、必要なアクセス権を持つアカウントを使用してください）：こちらから作成できます。
2. uvをインストールします（1行で完了します。Python と依存関係を管理するため、仮想環境は不要です）。

次に、ツール用のワンクリックボタンまたは1行のコマンドでサーバーを追加し、3つの JIRA_* 値を設定します。

Cursor

ボタンをクリックして Cursor で確定した後、~/.cursor/mcp.json（または Cursor Settings -> MCP）を開き、jira-admin のエントリに JIRA_BASE_URL、JIRA_EMAIL、JIRA_API_TOKEN を設定します。

Claude Code

コマンドを1つ実行します（3つの値はご自身のものに置き換えてください）。

claude mcp add --scope user \
  --env JIRA_BASE_URL=https://your-company.atlassian.net \
  --env [email protected] \
  --env JIRA_API_TOKEN=your_api_token_here \
  --transport stdio jira-admin \
  -- uvx jira-admin-mcp

--scope user を指定するとすべてのプロジェクトで利用できます。省略すると現在のプロジェクトだけに追加されます。claude mcp list で確認できます。

VS Code

インストール後、.vscode/mcp.json（またはユーザーの mcp.json）にある jira-admin のエントリに JIRA_* の値を設定します。

その他の MCP クライアント（手動）

次のブロックをクライアントの MCP 設定に追加します。

{
  "mcpServers": {
    "jira-admin": {
      "command": "uvx",
      "args": ["jira-admin-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

PyPI リリースではなく、未リリースの main を使いますか？"args": ["jira-admin-mcp"] を "args": ["--from", "git+https://github.com/its-qusai-nasr/jira-admin-mcp", "jira-mcp"] に置き換えてください。

設定ファイルの場所：Claude Desktop claude_desktop_config.json（macOS ~/Library/Application Support/Claude/、Windows %APPDATA%\Claude\）；Cursor ~/.cursor/mcp.json；VS Code .vscode/mcp.json（注：VS Code では "mcpServers" の代わりにトップレベルの "servers" キーを使用します）。編集後にクライアントを再起動すると、サーバーが jira-admin として表示され、78 個すべてのツールを利用できます。

ローカルクローン（開発用）

git clone https://github.com/its-qusai-nasr/jira-admin-mcp
cd jira-admin-mcp
uv sync                 # creates .venv and installs deps from uv.lock
cp .env.example .env    # then edit .env with your Jira credentials
uv run jira-mcp         # starts the server over stdio

---

設定

サーバーは環境変数（上記の env ブロック経由で渡すか、ローカルクローンを実行する際にプロジェクトディレクトリ内の .env ファイルから読み込みます）から設定を読み込みます。

変数	必須	説明
JIRA_BASE_URL	はい	Jira Cloud のベース URL。例：https://your-company.atlassian.net
JIRA_EMAIL	はい	API トークンを所有する Atlassian アカウントのメールアドレス
JIRA_API_TOKEN	はい	https://id.atlassian.com/manage-profile/security/api-tokens から取得した API トークン
JIRA_DRY_RUN	いいえ	true にすると、すべての書き込み（POST/PUT/DELETE）をシミュレートし、Jira を呼び出さずに送信される予定のペイロードを返します。デフォルトは false です。

**ヒント：**最初のセッションでは JIRA_DRY_RUN=true に設定してください。各書き込みツールは {"dry_run": true, "would_call": ...} のプレビューを返すため、ライブデータに変更を加える前に、エージェントが実行しようとしている内容を確認できます。

---

依頼できること

接続すると、アシスタントに次のような操作を依頼できます。

• 「[email protected] を jira-developers グループに追加して。」
• 「Team カスタムフィールドの対象を、Story と Bug の課題タイプについて、プロジェクト ENG と OPS のみに制限して。」
• 「権限スキーム 10789 を共有しているプロジェクトはどれですか？ほかのプロジェクトに影響を与えずに編集したいです。」
• 「プロジェクト OPS の Internal Task をすべて Task タイプに変更してから、未完了のものを In Progress に遷移して。」
• 「自分に割り当てられた未解決のバグを対象とする保存済みフィルターを作成して、開発者グループと共有して。」
• 「PROJ-123 の変更履歴を表示して、誰が再オープンしたか教えて。」

---

ツール（合計 78 個）

課題（12）

ツール	説明
jira_issues_search	ページネーションを使って JQL で課題を検索
jira_issues_get	キーを指定して単一の課題を取得（概要または詳細全体）
jira_issues_create	プロジェクト、タイプ、フィールドを指定して課題を作成
jira_issues_update	既存の課題のフィールドを更新
jira_issues_transition	新しいステータスに遷移（遷移 ID を自動解決）
jira_issues_assign	課題を割り当てる／割り当てを解除する
jira_issues_get_transitions	利用可能なワークフロー遷移を一覧表示
jira_issues_get_createmeta	課題の作成に必要なフィールドを取得
jira_issues_delete	課題を完全に削除
jira_issues_link	2 つの課題間にリンクを作成
jira_issues_get_changelog	監査履歴を取得（誰が何を変更したか）
jira_issues_bulk_create	最大 50 件の課題を一括作成

コメント（2）

ツール	説明
jira_comments_list	課題のコメントを一覧表示
jira_comments_add	コメントを追加（プレーンテキストは自動的に ADF に変換）

ユーザー（2）

ツール	説明
jira_users_search	メールアドレスまたは表示名で検索
jira_users_get	アカウント ID を指定してユーザーの詳細と所属グループを取得

グループ（6）

ツール	説明
jira_groups_list	メンバー数とともにグループを一覧表示
jira_groups_get_members	グループのメンバーを取得
jira_groups_add_user	ユーザーをグループに追加
jira_groups_remove_user	ユーザーをグループから削除
jira_groups_create	新しいグループを作成
jira_groups_delete	グループを削除

プロジェクト（10）

ツール	説明
jira_projects_list	名前またはキーで絞り込んでプロジェクトを一覧表示します
jira_projects_get	プロジェクトの詳細と課題タイプを取得します
jira_projects_get_statuses	課題タイプごとにグループ化されたすべてのステータスを取得します
jira_projects_get_roles	アクター（ユーザー／グループ）を含むロールを取得します
jira_projects_update_role	プロジェクトロールのアクターを追加または削除します
jira_projects_get_versions	プロジェクトのバージョン／リリースを一覧表示します
jira_projects_create_version	新しいバージョン／リリースを作成します
jira_projects_get_features	有効または無効な機能を取得します
jira_projects_get_notification_scheme	通知スキームを取得します
jira_projects_get_categories	プロジェクトカテゴリーを一覧表示します

権限（4）

ツール	説明
jira_permissions_list_schemes	すべての権限スキームを一覧表示します
jira_permissions_get_scheme	すべての許可設定を含むスキームを取得します
jira_permissions_add_grant	スキームに権限の許可設定を追加します
jira_permissions_assign_scheme	プロジェクトにスキームを割り当てます

カスタムフィールド（12）

ツール	説明
jira_fields_search	フィールドを名前で検索し、フィールド ID を確認します
jira_fields_get_contexts	カスタムフィールドのコンテキストを取得します
jira_fields_get_options	選択／ドロップダウンフィールドのオプションを取得します
jira_fields_manage_options	フィールドのオプションを追加、更新、または並べ替えます
jira_fields_create_context	コンテキストを作成します。必要に応じてプロジェクト／課題タイプを対象に設定できます
jira_fields_update_context	コンテキストの名前または説明を変更します
jira_fields_delete_context	コンテキストとそのオプションを削除します
jira_fields_assign_context_projects	コンテキストの対象を特定のプロジェクトに限定します
jira_fields_remove_context_projects	コンテキストの対象からプロジェクトを除外します
jira_fields_add_context_issuetypes	コンテキストの対象を特定の課題タイプに限定します
jira_fields_remove_context_issuetypes	コンテキストから課題タイプを除外します
jira_fields_get_project_mapping	各コンテキストの対象プロジェクトを監査します

フィルター（10）

ツール	説明
jira_filters_search	保存済みの JQL フィルターを検索します
jira_filters_create	新しい保存済み JQL フィルターを作成します
jira_filters_get	所有者と共有権限を含むフィルターを取得します
jira_filters_update	名前／JQL／説明を更新します
jira_filters_delete	フィルターを完全に削除します
jira_filters_change_owner	フィルターの所有者を変更します
jira_filters_get_shares	フィルターの共有権限を一覧表示します
jira_filters_add_share	共有設定を追加します（フィルターの所有者である必要があります）
jira_filters_remove_share	共有権限を削除します
jira_filters_force_add_share	所有していないフィルターに共有設定を追加します（所有者を入れ替える回避策）

課題リンク、ステータス（2）

ツール	説明
jira_issue_link_types_list	利用可能なリンクタイプ（Blocks、Relates など）を一覧表示します
jira_statuses_search	インスタンス全体のステータスを検索します

ワークフロー（8）

ツール	説明
jira_workflows_search	ワークフローを名前で検索します
jira_workflows_get_schemes	ワークフロースキームを一覧表示します
jira_workflows_get_scheme_mappings	課題タイプとワークフローのマッピングを取得します
jira_workflows_get_scheme_project_usages	スキームを使用しているプロジェクトを一覧表示します（共有スキームの安全性チェック）
jira_workflows_set_scheme_issuetype	課題タイプをワークフローにマッピングします
jira_workflows_delete_scheme_issuetype	課題タイプのワークフローマッピングを削除します
jira_workflows_create_scheme_draft	編集可能なスキームのドラフトを作成します
jira_workflows_publish_scheme_draft	スキームのドラフトを公開し、運用環境に反映します

課題タイプ、画面（6）

| ツール | 説明 | |---|---| | `jira_issuetypes_list` | 課題タイプを一覧表示します（プロジェクトで絞り込むこともできます） | | `jira_issuetypes_get_schemes` | 課題タイプスキームを一覧表示します | | `jira_issuetypes_get_scheme_mappings` | スキーム内の課題タイプを取得します | | `jira_screens_list` | 画面を一覧表示します | | `jira_screens_get_fields` | 画面タブ上のフィールドを取得します | | `jira_screens_get_schemes` | 画面スキームを一覧表示します |

一括操作、タスク（4）

ツール	説明
jira_bulk_edit_issues	複数の課題のフィールドを一括編集します
jira_bulk_transition_issues	課題を新しいステータスへ一括トランジションします
jira_tasks_get_status	ID を指定して、一般タスクまたは一括キュータスクの状態を確認します
jira_tasks_cancel	一般的な非同期タスクのキャンセルをリクエストします

---

設計上の注意点

• ラップではなく統合 — すべての REST エンドポイントを 1 対 1 で複製するのではなく、ワークフローを重視した 78 個のツールに集約しています。
• ドライラン — JIRA_DRY_RUN=true を設定すると、すべての書き込み操作でシミュレーション結果が返されます。
• レスポンスのフィルタリング — self、_links、avatarUrls などの不要な情報を除去し、エージェントには有用なフィールドのみを表示します。
• 詳細レベル — 読み取りツールでは、detail="summary"（デフォルト）または detail="full" を指定できます。
• ADF の自動ラップ — コメントや説明のプレーンテキストは、Atlassian Document Format に自動変換されます。
• トランジションの解決 — jira_issues_transition はステータス名からトランジション ID を自動的に解決します。
• 対処可能なエラー — エラーメッセージには、何が問題だったのか、次に何を試せばよいのかが示されます。
• トークン認証の適用範囲 — webhook エンドポイント（/webhook）は意図的にラップしていません。Atlassian はこれらの利用を Connect／OAuth 2.0 アプリに制限しており、トークン認証では要件を満たせないためです。

---

ローカルでのテスト

MCP Inspector を使って、ツールを対話的に調査、呼び出します。

npx @modelcontextprotocol/inspector uvx --from . jira-mcp

ネットワーク呼び出しなしでユニットテストを実行します。

uv sync --extra dev
uv run pytest
uv run ruff check .

---

セキュリティ

• 認証情報を絶対にコミットしないでください。 .env は gitignore されています。クライアント設定の env ブロックまたは OS のシークレットマネージャーを使用してください。
• 最小権限を適用してください。 API トークンは Jira ユーザーとして機能します。特に書き込み／管理者ツールを使う場合は、必要な権限だけを持つアカウントを使用してください。
• まずドライランで始めてください。 JIRA_DRY_RUN=true を設定すると、本番運用を開始する前に、実行予定のすべての書き込み操作を確認できます。
• 公式の MCP セキュリティのベストプラクティスを参照してください。

---

コントリビューション

Issue と PR を歓迎します。CONTRIBUTING.md をご覧ください。

ライセンス

MIT