mcp-jira

JIRA の Issue 検索・詳細取得・更新機能を提供する MCP サーバー。

インストール

バイナリをダウンロード

Releases ページ から環境に合ったバイナリをダウンロード：

プラットフォーム	ファイル名
macOS (Apple Silicon)	mcp-jira-darwin-arm64
Linux (x64)	mcp-jira-linux-x64
Windows (x64)	mcp-jira-windows-x64.exe

ダウンロード後、PATH の通った場所に配置して実行権限を付与：

chmod +x mcp-jira-*
mv mcp-jira-* ~/.local/bin/mcp-jira

ソースからビルド

git clone https://github.com/tjun1/mcp-jira.git
cd mcp-jira
./install.sh

~/.local/bin/mcp-jira にバイナリがインストールされる。

前提条件: Bun がインストールされていること。

セットアップ

Atlassian API トークンの取得

1. Atlassian API トークン管理ページ にアクセス
2. 「API トークンを作成」をクリック
3. トークンに名前を付けて「作成」
4. 表示されたトークンをコピーして安全に保管（再表示不可）

プロジェクトキーの確認方法

JIRA の Issue を開き、Issue キーを確認する：

PROJ-123
^^^^
これがプロジェクトキー

または、プロジェクト設定 → プロジェクトの詳細 で確認できる。

環境変数

変数名	必須	説明
JIRA_BASE_URL	○	JIRA の URL（例: https://your-domain.atlassian.net）
JIRA_EMAIL	△	Atlassian アカウントのメールアドレス
JIRA_API_TOKEN	△	Atlassian API トークン
JIRA_BEARER_TOKEN	△	Bearer トークン（Email + API Token の代わりに使用可）
JIRA_DEFAULT_PROJECTS	-	検索対象のプロジェクトをカンマ区切りで指定（例: PROJ1,PROJ2）

認証方式: JIRA_EMAIL + JIRA_API_TOKEN（Basic認証）または JIRA_BEARER_TOKEN のいずれかが必要。

MCP クライアントへの設定

グローバル設定（~/.claude/）

すべてのプロジェクトで使いたい場合、~/.claude/claude_desktop_config.json に設定する：

{
  "mcpServers": {
    "jira": {
      "command": "/Users/your-name/.local/bin/mcp-jira",
      "args": [],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_DEFAULT_PROJECTS": "PROJ1,PROJ2"
      }
    }
  }
}

プロジェクトローカル設定（.mcp.json）

特定のプロジェクトでのみ使いたい場合、プロジェクトルートに .mcp.json を作成する：

{
  "mcpServers": {
    "jira": {
      "command": "/Users/your-name/.local/bin/mcp-jira",
      "args": [],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_DEFAULT_PROJECTS": "PROJECT"
      }
    }
  }
}

.mcp.json をバージョン管理しない

.mcp.json には API トークンなどの認証情報が含まれるため、絶対にバージョン管理に含めてはいけない。

.gitignore に追加：

.mcp.json

リポジトリには mcp.example.json が含まれています。これをコピーして使用してください：

cp mcp.example.json .mcp.json
# .mcp.json を編集して、自分の環境に合わせて設定

VSCode + GitHub Copilot

VSCode の GitHub Copilot から mcp-jira を利用できる。

前提条件:

• VS Code 1.102 以降
• GitHub Copilot 拡張機能
• GitHub Copilot Chat 拡張機能

セットアップ手順

プロジェクトルートに .vscode/mcp.json を作成する。設定方法は2つある。

方法1: シンプルな設定（inputs 不使用）

API トークンを設定ファイルに直接記述する方法。

手順:

1. .vscode ディレクトリを作成（存在しない場合）

   mkdir -p .vscode
   

2. .vscode/mcp.json を作成して以下を記述

   {
     "servers": {
       "jira": {
         "command": "$HOME/.local/bin/mcp-jira",
         "args": [],
         "env": {
           "JIRA_BASE_URL": "https://your-domain.atlassian.net",
           "JIRA_EMAIL": "your-email@example.com",
           "JIRA_API_TOKEN": "your-api-token",
           "JIRA_DEFAULT_PROJECTS": "PROJ1,PROJ2"
         }
       }
     }
   }
   

3. VSCode を再起動

4. GitHub Copilot Chat から @jira として利用可能

方法2: 推奨設定（inputs 使用）

API トークンを起動時にプロンプトで入力する方法。認証情報がファイルに残らないため安全。

手順:

1. .vscode ディレクトリを作成（存在しない場合）

   mkdir -p .vscode
   

2. .vscode/mcp.json を作成して以下を記述

   {
     "inputs": {
       "jiraApiToken": {
         "type": "promptString",
         "password": true,
         "description": "JIRA API Token"
       }
     },
     "servers": {
       "jira": {
         "command": "$HOME/.local/bin/mcp-jira",
         "args": [],
         "env": {
           "JIRA_BASE_URL": "https://your-domain.atlassian.net",
           "JIRA_EMAIL": "your-email@example.com",
           "JIRA_API_TOKEN": "${input:jiraApiToken}",
           "JIRA_DEFAULT_PROJECTS": "PROJ1,PROJ2"
         }
       }
     }
   }
   

3. VSCode を再起動

4. GitHub Copilot を使用する際、API トークンの入力プロンプトが表示される（password: true により入力内容は隠される）

サンプルファイルの利用

プロジェクトルートの mcp.vscode.example.json をコピーして使うこともできる：

mkdir -p .vscode
cp mcp.vscode.example.json .vscode/mcp.json
# エディタで .vscode/mcp.json を開いて環境に合わせて編集

Claude Desktop との形式の違い

項目	Claude Desktop	VSCode
設定ファイル	~/.claude/claude_desktop_config.json または .mcp.json	.vscode/mcp.json
ルートキー	mcpServers	servers
command	絶対パスが必要	$HOME 変数が使える
機密情報	env に直接記述	inputs で変数化可能

注意事項

• .vscode/mcp.json には認証情報が含まれるため、バージョン管理から除外すること（.gitignore に追加済み）
• チームで設定を共有する場合は、各自が mcp.vscode.example.json をコピーして .vscode/mcp.json を作成する運用にする

利用可能なツール

MCP クライアント（Claude など）に対して、ツール名を明示して指示するのが基本。 ただし、会話の文脈から判断してくれることもあるため、必須ではない。

jira_search

JIRA の Issue を JQL で検索する。

引数:

• jql: JQL クエリ（必須）
• maxResults: 取得件数（1-100、デフォルト10）
• startAt: 開始位置（ページネーション用）

デフォルトプロジェクトフィルタリング:

環境変数 JIRA_DEFAULT_PROJECTS に設定したプロジェクトが自動的にフィルタ条件に追加される。

例：JIRA_DEFAULT_PROJECTS=PROJ1,PROJ2 の場合

status = Open
↓ 自動的に以下に変換される
(status = Open) AND project in (PROJ1, PROJ2)

ORDER BY 句も正しく処理される：

status = Open order by created desc
↓
(status = Open) AND project in (PROJ1, PROJ2) order by created desc

使い方の例:

• 「jira_search を使って未完了のチケットを探して」
• 「jira_search で最近更新された Issue を検索して」
• 「status = Open AND assignee = currentUser() で検索して」

jira_get_issue

Issue の詳細情報を取得する。

引数:

• issueIdOrKey: Issue キーまたはID（必須、例: PROJ-123）
• expand: 展開フィールド（デフォルト: renderedFields,names）
• maxChars: 最大文字数（1000-200000、デフォルト20000）

返却内容:

• Issue の基本情報（Key, Summary, Status, Assignee等）
• Description（Markdown 形式に変換）
• Comments
• Attachments

使い方の例:

• 「jira_get_issue で PROJ-123 の詳細を見せて」
• 「jira_get_issue でそのチケットの内容を取得して」

jira_get_transitions

Issue で利用可能なステータス遷移（トランジション）を取得する。

引数:

• issueIdOrKey: Issue キーまたはID（必須、例: PROJ-123）

返却内容:

• トランジションID（ステータス変更時に使用）
• トランジション名
• 遷移先ステータス（ID と名前）

使い方の例:

• 「jira_get_transitions で PROJ-123 のステータス変更可能な選択肢を見せて」
• 「このチケットのトランジション一覧を取得して」

jira_transition_issue

Issue のステータスを変更する。

引数:

• issueIdOrKey: Issue キーまたはID（必須、例: PROJ-123）
• transitionId: トランジションID（必須、例: "11"）

注意事項:

• 事前に jira_get_transitions で利用可能なトランジションIDを確認すること
• 権限がない場合や、ワークフローで許可されていないトランジションは実行できない

使い方の例:

• 「まず jira_get_transitions で PROJ-123 のトランジションを確認して、適切なIDで jira_transition_issue を実行して」
• 「このチケットを In Progress に進めて」

jira_add_comment

Issue にコメントを追加する。

引数:

• issueIdOrKey: Issue キーまたはID（必須、例: PROJ-123）
• comment: コメント内容（必須、プレーンテキスト）

返却内容:

• コメントID
• コメント作成者
• 作成日時

使い方の例:

• 「jira_add_comment で PROJ-123 に『レビュー完了しました』とコメントして」
• 「このチケットに進捗状況をコメントして」

jira_update_description

Issue の概要欄（description）を更新する。既存の内容を完全に上書きする。

引数:

• issueIdOrKey: Issue キーまたはID（必須、例: PROJ-123）
• description: 更新内容（必須、Markdown形式）

対応するMarkdown記法:

• 見出し（# ## ### など）
• 段落（空行で区切る）

使い方の例:

• 「jira_update_description で PROJ-123 の概要欄を『## 背景\n〇〇という問題がある。』に更新して」
• 「まず jira_get_issue で PROJ-123 の内容を取得し、概要欄に受け入れ条件を追加して更新して」

Claude Code Skills

Claude Code で使える便利なスキル（スラッシュコマンド）を提供しています。

インストール方法

リリースからインストール（推奨）

# スキルをダウンロードして展開
curl -L -o skills.tar.gz https://github.com/tjun1/mcp-jira/releases/latest/download/skills.tar.gz
mkdir -p ~/.claude/skills
tar -xzf skills.tar.gz -C ~/.claude/skills
rm skills.tar.gz

ソースからインストール

mkdir -p ~/.claude/skills
cp -r skills/* ~/.claude/skills/

利用可能なスキル

スキル	説明	使い方
/jira-search	JQLでIssueを検索	/jira-search status != Done
/jira-get	Issue詳細を取得	/jira-get PROJ-123
/jira-list-open	未完了チケット一覧	/jira-list-open
/jira-my-issues	自分のチケット一覧	/jira-my-issues
/jira-get-transitions	利用可能なトランジション取得	/jira-get-transitions PROJ-123
/jira-transition	ステータス変更	/jira-transition PROJ-123 11
/jira-add-comment	コメント追加	/jira-add-comment PROJ-123 レビュー完了
/jira-update-description	概要欄を更新	/jira-update-description PROJ-123 ## 背景\n〇〇

スキルの使い方

Claude Code で / を入力すると、利用可能なスキル一覧が表示されます。

例：

/jira-search priority = High AND status != Done
/jira-get ME-382
/jira-list-open
/jira-my-issues

開発者向け情報

開発環境のセットアップ

git clone https://github.com/tjun1/mcp-jira.git
cd mcp-jira
bun install

環境変数の設定

.env ファイルを作成（Bun が自動で読み込む）：

JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-api-token
JIRA_DEFAULT_PROJECTS=PROJ1,PROJ2

実行

bun run src/index.ts

テスト

bun test

License

MIT License. See LICENSE for details.