jira-easy-mcp

jira-easy-mcp

認証トークンなしで Jira を利用できる、もうひとつの Model Context Protocol（MCP）サーバーです。課題、プロジェクト、ボード、スプリント、コメント、作業ログなど、Jira の包括的な自動化に対応するツールを提供します。

テスト済みの環境： Jira Server / Data Center 7.13、8.20、9.12、10.3（すべてのツールを自動テスト済みです。詳しくは開発とテストをご覧ください）

---

🔑 この MCP を選ぶ理由

ベーシック認証（ユーザー名＋パスワード）に対応 — API トークンは不要です！

多くの Jira MCP サーバーは OAuth または API トークンを必要としますが、これらは多くの組織で制限されているか、許可されていません。この MCP はHTTP ベーシック認証を使用するため、Jira のユーザー名とパスワードだけで接続できます。次のような環境に最適です。

• 🏢 管理者が API トークンの作成を許可していないエンタープライズ環境
• 🔒 OAuth が設定されていないセルフホストの Jira Server インスタンス
• ⚡ IT の承認手続きを経ずにすばやくセットアップしたい場合

---

クイックスタート

VS Code（ワークスペース設定）

ワークスペースのルートに .vscode/mcp.json を作成します。

{
  "servers": {
    "jira": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "jira-easy-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://your-jira-instance.com",
        "JIRA_USERNAME": "your-username",
        "JIRA_PASSWORD": "your-password",
        "JIRA_PROJECTS_FILTER": "ABC,DEF,XYZ",
        "JIRA_RESPONSE_FORMAT": "JSON"
      }
    }
  }
}

すべてのワークスペースからアクセスするには、VS Code の設定に追加します。

注： JIRA_PROJECTS_FILTER と JIRA_RESPONSE_FORMAT は任意です。プロジェクトフィルターを設定すると、指定したプロジェクトへのアクセスに制限されます。レスポンス形式には JSON（デフォルト）または TOON（テキスト指向の表記法）を指定できます。

Claude Code

claude mcp add jira \
  -e JIRA_BASE_URL=https://your-jira-instance.com \
  -e JIRA_USERNAME=your-username \
  -e JIRA_PASSWORD=your-password \
  -- npx -y jira-easy-mcp

Codex CLI

~/.codex/config.toml に追加します。

[mcp_servers.jira]
command = "npx"
args = ["-y", "jira-easy-mcp"]
env = { JIRA_BASE_URL = "https://your-jira-instance.com", JIRA_USERNAME = "your-username", JIRA_PASSWORD = "your-password" }

その他のクライアント

Cursor： ~/.cursor/mcp.json または .cursor/mcp.json（"mcpServers": { ... } のラッパーを使用）
Windsurf： Windsurf の MCP 設定に追加（"mcpServers": { ... } のラッパーを使用）
Claude Desktop： claude_desktop_config.json を編集（macOS：~/Library/Application Support/Claude/、Windows：%APPDATA%\Claude\。"mcpServers": { ... } のラッパーを使用）
Gemini CLI： ~/.gemini/settings.json（"mcpServers": { ... } のラッパーを使用）

いずれも、上記の VS Code と同じ command、args、env の設定を使用します。

Windows： クライアントが npx を起動できない場合は、"command": "cmd" と "args": ["/c", "npx", "-y", "jira-easy-mcp"] を使用してください。

ツールの上限： 一部のクライアント（特に Cursor）では、モデルに送信するツール数に上限があり、従来はすべてのサーバーを合わせて約 40 個でした。このサーバーには 41 個のツールがあるため、クライアントの MCP 設定で不要なツールを無効にしてください。

OS のキーチェーンから認証情報を取得する（任意）

パスワードを設定ファイルに記載しないようにするには、JIRA_USERNAME と JIRA_PASSWORD を省略し、サービス名 JiraMCP で認証情報を保存します。

• macOS： security add-generic-password -s JiraMCP -a your-username -w（パスワードの入力が求められます。初回起動時には、node による読み取りを macOS が許可するか確認します）
• Windows： cmdkey /generic:JiraMCP /user:your-username /pass（/add ではなく /generic を使用してください）

複数のアカウントが保存されている場合は、JIRA_USERNAME を設定して使用するアカウントを選択します。JIRA_USERNAME と JIRA_PASSWORD の両方が設定されている場合は、それらが使用され、キーチェーンは読み取られません。キーチェーンのサポートには任意の keytar パッケージを使用します。お使いのマシンにインストールできない場合は、環境変数を使用してください。

---

一般的なユースケース

タスク	ツール	プロンプトの例
課題を検索する	jira_search	"プロジェクト ABC で、自分に割り当てられている未解決のバグをすべて検索してください"
課題の詳細を取得する	jira_get_issue	"課題 ABC-123 の詳細を表示してください"
課題の画像を表示する	jira_get_issue_images	"ABC-123 に添付されているスクリーンショットを表示してください"
添付ファイルをアップロードする	jira_upload_attachment	" /Users/me/Desktop/error.png を ABC-123 に添付してください"
課題を作成する	jira_create_issue	"プロジェクト ABC に「ログインボタンが動作しない」というタイトルの新しいバグを作成してください"
課題を更新する	jira_update_issue	"ABC-123 の優先度を High に変更し、john.doe に割り当ててください"
カスタムフィールドを編集する	jira_update_issue + jira_get_edit_meta	"ABC-123 の Severity を Critical に設定してください"（一意の名前、または customfield_ ID）
コメントを追加する	jira_add_comment	"ABC-123 に「ステージング環境への修正のデプロイが完了しました」というコメントを追加してください"
ステータスを変更する	jira_transition_issue	"ABC-123 を Done に移動してください"
作業時間を記録する	jira_add_worklog	"昨日の ABC-123 の作業時間を 2 時間として記録してください"
プロジェクトを一覧表示する	jira_get_projects	"アクセス権のあるプロジェクトをすべて表示してください"
スプリントを表示する	jira_get_sprints	"プロジェクト ABC の現在のスプリントには何がありますか？"
課題をリンクする	jira_create_link	"ABC-123 が ABC-124 をブロックするようにリンクしてください"
フィルター URL を生成する	jira_generate_filter_url	"過去 7 日間に更新された未解決のバグすべてを表示する共有可能なリンクを作成してください"

---

MCP Inspector でのテスト

MCP Inspector では、Web UI を使ってすべてのツールを対話形式でテストできます。

npx @modelcontextprotocol/inspector npx jira-easy-mcp

ブラウザーで http://localhost:6274 が開き、次の操作ができます。

• 利用可能なすべてのツールを表示する
• 各ツールにカスタムパラメーターを指定してテストする
• 生の JSON レスポンスを確認する

注： 接続する前に、Inspector の UI に次の値を入力してください。JIRA_BASE_URL、JIRA_USERNAME、JIRA_PASSWORD。

---

カスタムフィールド

Jira REST API v2 では、カスタムフィールドを ID（customfield_10006）で識別します。値には、そのフィールドの型に対応する未加工の REST ペイロードを指定します。表示名を使用できるのは、該当する画面で名前が一意（大文字と小文字を区別して完全一致）である場合のみです。

読み取り（jira_get_issue）

デフォルトのレスポンスには、システムフィールドと、現在値が設定されているカスタムフィールドが { "id", "name", "value" } の形式で含まれます。include: ["comments"]（および／または worklogs、attachments）を指定しない限り、コメント、作業ログ、添付ファイルは省略されます。customFields: "all" または fields を指定しない限り、値が null のカスタムフィールドは省略されます。

fields を指定すると、カスタムフィールドの GET 対象を絞り込めます（customfield_11205 のような ID、または Severity のような編集画面で一意の名前を指定します）。指定したフィールドは、値が null の場合も返されます。名前は GET /field ではなく、この課題の expand=names から取得されます。

{
  "key": "ABC-123",
  "customFields": [
    { "id": "customfield_10006", "name": "Story Points", "value": 5 },
    { "id": "customfield_10107", "name": "Flagged", "value": { "value": "Yes" } }
  ]
}

書き込み（jira_update_issue / jira_create_issue）

customFields には、ID（customfield_10006）または jira_get_edit_meta / jira_get_create_meta で取得した一意の名前をキーとして指定します。ID の場合、追加の GET は不要です。名前は、その課題タイプのメタデータに基づいて解決されます。同じ名前が複数ある場合は安全のため処理に失敗するため、ID を使用してください。書き込みの前に毎回 jira_get_fields を呼び出す必要はありません。

スキーマの type	REST 値
string / number / date	"text"、5、"2011-10-03"
option（選択肢）	{ "value": "Yes" } または { "id": "10100" }
user（Server）	{ "name": "username" } — Cloud の accountId は使用しません
option の配列	[{ "value": "A" }, { "value": "B" }]（itemsType: option）
クリア	null

jira_get_fields に一覧表示されていても、編集／作成メタデータにないフィールドはその画面には存在せず、更新できません。

検索（jira_search）

デフォルトの検索で返されるのはシステムフィールドのみです（カスタムフィールドやコメント／作業ログ／添付ファイルのデータは含まれません）。fields は追加項目を指定します。システムキーと customfield_ ID はそのまま渡され、表示名はキャッシュを使用しない最新の GET /field で解決されます。ID の使用を推奨します。曖昧な名前は安全のため処理に失敗します。

カタログ（jira_get_fields）

JQL の句の名前を確認する際に使用します。すべての作成／更新の前処理として使うものではありません。課題タイプのフィールドについては、jira_get_edit_meta または jira_get_create_meta を使用してください。

---

オプションの環境変数

変数	デフォルト	説明
JIRA_PROJECTS_FILTER	(なし)	カンマ区切りのプロジェクトキーです。このリストに含まれない課題キー／プロジェクトキーはツールで拒否されます（課題 ID はキーで指定する必要があります）。JQL の対象もこれらのプロジェクトに限定されます。ボード、スプリント、リンクの ID は検証されません
JIRA_RESPONSE_FORMAT	JSON	レスポンス形式：JSON または TOON
JIRA_LOG_LEVEL	INFO	ログの詳細度：DEBUG、INFO、WARN、ERROR
JIRA_TIMEOUT	30000	リクエストのタイムアウト（ミリ秒）
JIRA_RETRY_COUNT	3	タイムアウト、429、502～504 の場合の再試行回数です。書き込みリクエスト（POST）は 429 の場合のみ再試行されるため、Jira の応答が遅くても課題、コメント、リンクが重複することはありません
JIRA_RETRY_DELAY	1000	再試行間の基本待機時間（ミリ秒）
JIRA_SSL_VERIFY	true	SSL 検証をスキップするには false を設定します。会社の CA を使う場合は、NODE_EXTRA_CA_CERTS=/path/to/ca.pem を推奨します
JIRA_CACHE_TTL	300	静的データのキャッシュ TTL（秒）

jira_get_issue_images は、Jira の認証済み添付ファイル URL（/secure/attachment/...、Jira Server/Data Center）を通じて画像をダウンロードします。デフォルトでは最大 5 枚（最大 10 枚）の画像を返し、画像ごとの上限は 10 MiB、レスポンス全体の上限は 20 MiB です。 jira_upload_attachment は、サーバーを実行しているマシン上の絶対パスで指定されたローカルファイルを読み込みます。

---

トラブルシューティング

エラー	対処方法
Authentication failed ... restart the MCP server	認証情報が間違っています。最初の失敗後、サーバーはログインを停止するため、エージェントが繰り返し再試行しても Jira の CAPTCHA によるロックアウトは発生しません。認証情報を修正し、サーバーを再起動してください（またはクライアントで MCP サーバーを再読み込みしてください）。
Login blocked by CAPTCHA	ログイン失敗が多すぎます。ブラウザーで一度 Jira にログインしてから、再試行してください。
Jira redirected to ...	JIRA_BASE_URL が正しくありません。Jira がリダイレクトする場合は https:// を使用するか、コンテキストパスを追加してください。ログインページへのリダイレクトは、Jira の前段に SSO プロキシがあることを意味します。
No Jira REST API at ...	通常はコンテキストパスがありません。例：https://host ではなく https://host/jira を使用してください。
fetch failed / 証明書エラー	会社の CA を使う場合は、NODE_EXTRA_CA_CERTS=/path/to/ca.pem を指定してサーバーを起動してください。最終手段として、JIRA_SSL_VERIFY=false を設定してください。
... outside the allowed projects	このキーは JIRA_PROJECTS_FILTER に含まれていません。

---

開発とテスト

pnpm install
pnpm test              # unit tests + build (any OS, Node 18+)
node scripts/smoke.mjs # MCP handshake check (needs JIRA_BASE_URL set to anything)

実際の Jira に対してテストする場合（Docker、Node 20.10 以降）：ヘルパーが一時的な Jira を起動し、Atlassian の公開する3 時間限定のテスト用ライセンスでセットアップを完了したうえで、管理者（admin / Jira-IT-admin-1）、2 人目のユーザー、2 つの Scrum プロジェクト（IT、OT）を作成します。

pnpm jira:up 9.12 8080            # or 7.13, 8.20, 10.3 (Jira 10 also starts PostgreSQL)
JIRA_IT_BASE_URL=http://localhost:8080 pnpm test:integration
pnpm jira:down 9.12

pnpm jira:up 9.12 8080 /jira を実行すると、コンテキストパス配下で Jira を提供します。各インスタンスには Docker メモリが約 3 GB 必要です。メモリの少ないマシンでは、一度に 1 つだけ実行してください。キーチェーンのテストは、keytar が動作し、実際の JiraMCP 認証情報が存在しない環境でのみ実行され、テストで作成したものは削除されます。 CI では、Linux、macOS、Windows（Node 18～24）でユニットテストを実行し、上記の各バージョンに対して統合テストを実行します。

---

互換性

Jira バージョン	ステータス
Jira Server 7.12.1 / 7.12.3	✅ 手動でテスト済み
Jira Server 7.13	✅ 自動テスト済み（全ツール）
Jira Server / DC 8.20	✅ 自動テスト済み（全ツール）
Jira DC 9.12（/jira コンテキストパス配下でも対応）	✅ 自動テスト済み（全ツール）
Jira DC 10.3	✅ 自動テスト済み（全ツール）
Jira Cloud	︖ 未テスト（公式 MCP を使用してください）

Node.js 18 以降が必要です。CI では、macOS、Linux、Windows（Node.js 18～24）でユニットテストと MCP スモークテストを実行します。

問題を報告して、改善にご協力ください。