Atlassian Jira MCP Server

AIをJiraプロジェクトに接続する

Claude、Cursor AI、その他のAIアシスタントをJiraプロジェクト、課題、ワークフローに直接接続して、仕事の管理と進捗追跡の方法を変革しましょう。プロジェクトの分析情報をすぐに取得し、課題管理を効率化し、チームのコラボレーションを強化できます。

できること

• AIにプロジェクトについて質問する：「DEVプロジェクトで対応中の課題は何ですか？」
• 課題の分析情報を取得する：「コメントを含め、PROJ-123の詳細を表示してください」
• プロジェクトの進捗を追跡する：「自分に割り当てられた優先度の高い課題をすべて一覧表示してください」
• 課題のコメントを管理する：「テスト結果についてPROJ-456にコメントを追加してください」
• 複数のプロジェクトを横断して検索する：「自分のプロジェクト全体から対応中のバグをすべて探してください」
• 課題を作成・更新する：「MOBILEプロジェクトに新しいバグを作成してください」

こんな方に最適です

• 開発者：課題の詳細や開発コンテキストにすばやくアクセスしたい方
• プロジェクトマネージャー：進捗、優先順位、チームへの割り当てを追跡する方
• スクラムマスター：スプリントやワークフローの状態を管理する方
• チームリーダー：プロジェクトの健全性や課題の解決状況を監視する方
• QAエンジニア：バグやテスト状況を追跡する方
• すべての方：自然言語を使ってJiraを操作したい方

クイックスタート

2分で利用を開始できます。

1. Jiraの認証情報を取得する

Jira APIトークンを生成します。

1. Atlassian API Tokensにアクセスします
2. Create API tokenをクリックします
3. **「AI Assistant」**のような名前を付けます
4. 生成されたトークンをすぐにコピーします（再表示されません！）

2. すぐに試す

# Set your credentials
export ATLASSIAN_SITE_NAME="your-company"  # for your-company.atlassian.net
export ATLASSIAN_USER_EMAIL="[email protected]"
export ATLASSIAN_API_TOKEN="your_api_token"

# List your Jira projects
npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/project/search"

# Get details about a specific project
npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/project/DEV"

# Get an issue with JMESPath filtering
npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/issue/PROJ-123" --jq "{key: key, summary: fields.summary, status: fields.status.name}"

AIアシスタントに接続する

Claude Desktopをお使いの場合

Claudeの設定ファイル（~/.claude/claude_desktop_config.json）に次の内容を追加します。

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-jira"],
      "env": {
        "ATLASSIAN_SITE_NAME": "your-company",
        "ATLASSIAN_USER_EMAIL": "[email protected]",
        "ATLASSIAN_API_TOKEN": "your_api_token"
      }
    }
  }
}

Claude Desktopを再起動すると、ステータスバーにjiraサーバーが表示されます。

その他のAIアシスタントをお使いの場合

ほとんどのAIアシスタントはMCPに対応しています。サーバーをグローバルにインストールします。

npm install -g @aashari/mcp-server-atlassian-jira

次に、STDIOトランスポートを使ってMCPサーバーに接続するようAIアシスタントを設定します。

代替方法：設定ファイル

システム全体で使用する設定として、~/.mcp/configs.jsonを作成します。

{
  "jira": {
    "environments": {
      "ATLASSIAN_SITE_NAME": "your-company",
      "ATLASSIAN_USER_EMAIL": "[email protected]",
      "ATLASSIAN_API_TOKEN": "your_api_token"
    }
  }
}

代替の設定キー： "jira"の代わりに、"atlassian-jira"、"@aashari/mcp-server-atlassian-jira"、または"mcp-server-atlassian-jira"も使用できます。

利用可能なツール

このMCPサーバーは、任意のJira APIエンドポイントにアクセスできる汎用ツールを5つ提供します。

ツール	説明
jira_get	任意のJira APIエンドポイントにGETリクエストを送信（データの読み取り）
jira_post	任意のエンドポイントにPOSTリクエストを送信（リソースの作成）
jira_put	任意のエンドポイントにPUTリクエストを送信（リソースの置き換え）
jira_patch	任意のエンドポイントにPATCHリクエストを送信（部分更新）
jira_delete	任意のエンドポイントにDELETEリクエストを送信（リソースの削除）

よく使うAPIパス

プロジェクト：

• /rest/api/3/project/search - すべてのプロジェクトを一覧表示（ページネーション対応、推奨）
• /rest/api/3/project - すべてのプロジェクトを一覧表示（ページネーションなし、レガシー）
• /rest/api/3/project/{projectKeyOrId} - プロジェクトの詳細を取得

課題：

• /rest/api/3/search/jql - JQLで課題を検索（jqlクエリパラメーターを使用）。重要： /rest/api/3/searchは非推奨です！
• /rest/api/3/issue/{issueIdOrKey} - 課題の詳細を取得
• /rest/api/3/issue - 課題を作成（POST）
• /rest/api/3/issue/{issueIdOrKey}/transitions - トランジションを取得／実行

コメント：

• /rest/api/3/issue/{issueIdOrKey}/comment - コメントを一覧表示／追加
• /rest/api/3/issue/{issueIdOrKey}/comment/{commentId} - コメントを取得／更新／削除

作業ログ：

• /rest/api/3/issue/{issueIdOrKey}/worklog - 作業ログを一覧表示／追加
• /rest/api/3/issue/{issueIdOrKey}/worklog/{worklogId} - 作業ログを取得／更新／削除

ユーザーとステータス：

• /rest/api/3/myself - 現在のユーザーを取得
• /rest/api/3/user/search - ユーザーを検索（queryパラメーターを使用）
• /rest/api/3/status - すべてのステータスを一覧表示
• /rest/api/3/issuetype - 課題タイプを一覧表示
• /rest/api/3/priority - 優先度を一覧表示

TOON 出力形式

デフォルトでは、すべての応答で TOON（Token-Oriented Object Notation） 形式が使用されます。TOON は JSON と比べてトークン使用量を 30～60％削減します。表形式の配列と最小限の構文を使用するため、AI での利用に最適です。

JSON を使用するには： CLI コマンドに --output-format json を追加するか、MCP ツールの呼び出しで outputFormat: "json" を設定します。

TOON と JSON の例：

TOON: key|summary|status
      PROJ-1|First issue|Open
      PROJ-2|Second issue|Done

JSON: [{"key":"PROJ-1","summary":"First issue","status":"Open"},
       {"key":"PROJ-2","summary":"Second issue","status":"Done"}]

JMESPath によるフィルタリング

すべてのツールで、特定のデータを抽出するためのオプションの JMESPath（jq）フィルタリングを使用できます。

# Get just project names and keys
npx -y @aashari/mcp-server-atlassian-jira get \
  --path "/rest/api/3/project/search" \
  --jq "values[].{key: key, name: name}"

# Get issue key and summary
npx -y @aashari/mcp-server-atlassian-jira get \
  --path "/rest/api/3/issue/PROJ-123" \
  --jq "{key: key, summary: fields.summary, status: fields.status.name}"

応答の切り詰めと生ログ

大きな API 応答（40k 文字超 ≈ 10k トークン）は、ガイダンスとともに自動的に切り詰められます。完全な生の応答は、参照用に /tmp/mcp/mcp-server-atlassian-jira/<timestamp>-<random>.txt に保存されます。

切り詰められた場合、次の内容が表示されます：

• 生ファイルのパスを含む切り詰めの通知
• より適切なフィルターを使ってクエリを調整するための提案
• 表示されたデータと全体サイズの割合

実際の使用例

プロジェクトを確認する

AI アシスタントに尋ねます：

• 「アクセスできるすべてのプロジェクトを一覧表示して」
• 「DEV プロジェクトの詳細を表示して」
• 「名前に『Platform』という単語が含まれるプロジェクトはどれ？」

課題を検索して追跡する

AI アシスタントに尋ねます：

• 「DEV プロジェクトの優先度が高い課題をすべて検索して」
• 「自分に割り当てられていて、進行中の課題を表示して」
• 「過去 1 週間に報告されたバグを検索して」
• 「モバイルチームの未解決課題をすべて一覧表示して」

課題の詳細を管理する

AI アシスタントに尋ねます：

• 「コメントを含めて、課題 PROJ-456 の詳細をすべて取得して」
• 「PROJ-123 の現在のステータスと担当者は？」
• 「認証バグに関するコメントをすべて表示して」

課題について連絡する

AI アシスタントに尋ねます：

• 「PROJ-456 にコメントを追加して：『コードレビューが完了しました。テスト可能です』」
• 「ログインの課題に、ステージング環境にデプロイ済みだとコメントして」

CLI コマンド

CLI では MCP ツールと同じ機能を、ターミナルから直接利用できます：

# GET request (returns TOON format by default)
npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/project/search"

# GET with query parameters and JSON output
npx -y @aashari/mcp-server-atlassian-jira get \
  --path "/rest/api/3/search/jql" \
  --query-params '{"jql": "project=DEV AND status=\"In Progress\"", "maxResults": "10"}' \
  --output-format json

# GET with JMESPath filtering to extract specific fields
npx -y @aashari/mcp-server-atlassian-jira get \
  --path "/rest/api/3/issue/PROJ-123" \
  --jq "{key: key, summary: fields.summary, status: fields.status.name}"

# POST request (create an issue)
npx -y @aashari/mcp-server-atlassian-jira post \
  --path "/rest/api/3/issue" \
  --body '{"fields": {"project": {"key": "DEV"}, "summary": "New issue title", "issuetype": {"name": "Task"}}}'

# POST request (add a comment)
npx -y @aashari/mcp-server-atlassian-jira post \
  --path "/rest/api/3/issue/PROJ-123/comment" \
  --body '{"body": {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "My comment"}]}]}}'

# PUT request (update issue - full replacement)
npx -y @aashari/mcp-server-atlassian-jira put \
  --path "/rest/api/3/issue/PROJ-123" \
  --body '{"fields": {"summary": "Updated title"}}'

# PATCH request (partial update)
npx -y @aashari/mcp-server-atlassian-jira patch \
  --path "/rest/api/3/issue/PROJ-123" \
  --body '{"fields": {"summary": "Updated title"}}'

# DELETE request
npx -y @aashari/mcp-server-atlassian-jira delete \
  --path "/rest/api/3/issue/PROJ-123/comment/12345"

注： すべての CLI コマンドで次のオプションを使用できます：

• --output-format - toon（デフォルト、トークン効率重視）または json を選択します
• --jq - JMESPath 式で応答をフィルタリングします
• --query-params - クエリパラメーターを JSON 文字列として渡します

トラブルシューティング

「認証に失敗しました」または「403 Forbidden」

1. API トークンの権限を確認します：

   • Atlassian API トークンに移動します
   • トークンが有効で、期限切れになっていないことを確認します

2. サイト名の形式を確認します：

   • Jira の URL が https://mycompany.atlassian.net の場合
   • サイト名には mycompany のみを指定します

3. 認証情報をテストします：

   npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/myself"
   

「リソースが見つかりません」または「404」

1. API パスを確認します：

   • パスでは大文字と小文字が区別されます
   • プロジェクト名ではなく、プロジェクトキー（例：DEV）を使用します
   • 課題キーにはプロジェクトの接頭辞が含まれます（例：DEV-123）

2. アクセス権限を確認します：

   • ブラウザーでプロジェクトにアクセスできることを確認します
   • プロジェクトによっては、特定のユーザーにのみアクセスが制限されている場合があります

検索しても「結果が見つかりません」と表示される場合

1. 別の検索語を試します：

   • プロジェクト名ではなく、プロジェクトキーを使用します
   • より広い検索条件を試します

2. JQL の構文を確認します：

   • まず Jira の詳細検索で JQL を検証します

Claude Desktop との連携に関する問題

1. 設定ファイルを更新した後、Claude Desktop を再起動します
2. 設定ファイルの場所を確認します：
   • macOS：~/.claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

ヘルプを利用する

問題が解決しない場合：

1. 簡単なテストコマンドを実行して、すべてが動作することを確認します
2. 同様の問題について、GitHub Issuesを確認します
3. エラーメッセージとセットアップの詳細を添えて、新しい issue を作成します

よくある質問

どのような権限が必要ですか？

Atlassian アカウントには、次の権限が必要です：

• Jira へのアクセス：照会するプロジェクトに対する適切な権限
• API トークン：適切な権限（トークンの作成時に自動的に付与されます）

Jira Server（オンプレミス）で使用できますか？

現在、このツールは Jira Cloud のみをサポートしています。Jira Server/Data Center のサポートは、今後のバージョンで追加される可能性があります。

サイト名を確認するにはどうすればよいですか？

サイト名は Jira URL の最初の部分です。

• URL：https://mycompany.atlassian.net -> サイト名：mycompany
• URL：https://acme-corp.atlassian.net -> サイト名：acme-corp

どの AI アシスタントで使用できますか？

Model Context Protocol（MCP）をサポートする AI アシスタントであれば使用できます。

• Claude Desktop
• Cursor AI
• Continue.dev
• その他多数

データは安全ですか？

はい。このツールは次のように動作します。

• すべてローカルマシン上で実行されます
• ご自身の Jira 認証情報を使用します
• データが第三者に送信されることはありません
• アクセスを許可したものだけにアクセスします

複数のプロジェクトを横断して検索できますか？

はい。プロジェクト横断検索には JQL クエリを使用してください。たとえば、次のようにします。

npx -y @aashari/mcp-server-atlassian-jira get \
  --path "/rest/api/3/search/jql" \
  --query-params '{"jql": "assignee=currentUser() AND status=\"In Progress\""}'

技術詳細

最近の更新

バージョン 3.2.1（2025 年 12 月）：

• 30～60％のトークン削減を実現する TOON 出力形式を追加
• 大きなペイロード（>40k chars）に対するレスポンスの自動切り詰めを実装
• 参照用に、生の API レスポンスを /tmp/mcp/mcp-server-atlassian-jira/ に保存
• MCP SDK v1.23.0 に更新し、最新の registerTool API を採用
• 非推奨の /rest/api/3/search エンドポイントを修正（現在は /rest/api/3/search/jql を使用）
• すべての依存関係を最新バージョンに更新（Zod v4.1.13、Commander v14.0.2）

要件

• Node.js：18.0.0 以上
• MCP SDK：v1.23.0（最新の登録 API を使用）
• Jira：Cloud のみ（Server/Data Center はサポート対象外）

アーキテクチャ

このサーバーは 5 層の MCP アーキテクチャに従っています。

1. CLI 層 - Commander.js を使用した人間向けインターフェース
2. ツール層 - Zod による検証を備えた AI インターフェース
3. コントローラー層 - ビジネスロジックとオーケストレーション
4. サービス層 - Jira REST API の直接呼び出し
5. ユーティリティ層 - 横断的関心事（ログ記録、フォーマット、トランスポート）

デバッグ

DEBUG 環境変数を設定すると、デバッグログを有効にできます。

# In Claude Desktop config
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-jira"],
      "env": {
        "DEBUG": "true",
        "ATLASSIAN_SITE_NAME": "your-company",
        "ATLASSIAN_USER_EMAIL": "[email protected]",
        "ATLASSIAN_API_TOKEN": "your_api_token"
      }
    }
  }
}

デバッグログは ~/.mcp/data/mcp-server-atlassian-jira.<session-id>.log に書き込まれます。

生の API レスポンスを確認する： レスポンスが切り詰められた場合、リクエスト／レスポンスの詳細を含む完全な生レスポンスが /tmp/mcp/mcp-server-atlassian-jira/<timestamp>-<random>.txt に保存されます。

v2.x からの移行

バージョン 3.0 では、8 個以上の専用ツールを 5 個の汎用 HTTP メソッドツールに置き換えています。v2.x からアップグレードする場合：

以前（v2.x）：

jira_ls_projects, jira_get_project, jira_ls_issues, jira_get_issue,
jira_create_issue, jira_ls_comments, jira_add_comment, jira_ls_statuses, ...

以後（v3.0+）：

jira_get, jira_post, jira_put, jira_patch, jira_delete

移行例：

• jira_ls_projects -> パス /rest/api/3/project/search を指定した jira_get
• jira_get_project -> パス /rest/api/3/project/{key} を指定した jira_get
• jira_get_issue -> パス /rest/api/3/issue/{key} を指定した jira_get
• jira_create_issue -> パス /rest/api/3/issue を指定した jira_post
• jira_add_comment -> パス /rest/api/3/issue/{key}/comment を指定した jira_post
• jira_ls_statuses -> パス /rest/api/3/status を指定した jira_get

v3.0+ のメリット：

• 任意の Jira REST API v3 エンドポイントにフルアクセス（事前定義されたツールに限定されません）
• 効率的なデータ抽出のための JMESPath フィルタリング
• すべての HTTP メソッドで一貫したインターフェース
• 30～60％のトークンを節約できる TOON 形式
• 生ファイルへのログ記録を伴うレスポンスの自動切り詰め

サポート

お困りですか？サポートを受ける方法は次のとおりです。

1. 上記のトラブルシューティングセクションを確認してください - よくある問題のほとんどを取り上げています
2. GitHub リポジトリをご覧ください。ドキュメントと使用例を掲載しています：github.com/aashari/mcp-server-atlassian-jira
3. 問題を報告してください：GitHub Issues
4. 機能リクエストや一般的な質問については、ディスカッションを開始してください

---

プロジェクト管理のワークフローに AI を取り入れたいチームのために、心を込めて作りました。