mcp-jira

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

インストール

バイナリをダウンロード

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

ダウンロード後、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 がインストールされていること。

Related MCP server: jira-mcp

セットアップ

Atlassian API トークンの取得

1. Atlassian API トークン管理ページ にアクセス

2. 「API トークンを作成」をクリック

3. トークンに名前を付けて「作成」

4. 表示されたトークンをコピーして安全に保管（再表示不可）

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

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

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

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

環境変数

認証方式: 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 との形式の違い

注意事項

• .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/

利用可能なスキル

スキルの使い方

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.