mcp-atlassian-extended

mcp-atlassian-extended

インストール： uvx mcp-atlassian-extended | PyPI | MCP Registry | 変更履歴

uvx mcp-atlassian-extended                          # with writes
MCP_READ_ONLY=true uvx mcp-atlassian-extended       # locked read-only: write tools are not listed

mcp-atlassian-extended は、Jira と Confluence 向けの Model Context Protocol（MCP） サーバーです。Jira と Confluence での作業に使える 22 個のツール、15 個のリソース、5 個のプロンプトを AI アシスタントに提供します。カスタムフィールドを使った課題の作成と更新、課題のリンク、添付ファイルの管理、ユーザーの検索ができます。また、アジャイルボードやスプリントの操作、プロジェクトバージョンの追跡（API v2）、チームカレンダーの閲覧、スプリントキャパシティの計画も行えます。mcp-atlassian を、ツールの重複なしで拡張します。書き込み可能モード、または読み取り専用に固定するモード（MCP_READ_ONLY=true）のいずれかで実行できます。読み取り専用モードでは、10 個の書き込みツールがモデルに提示されることはありません。

このサーバーは MCP 2026-07-28 仕様（MCP 2.0 と呼ばれることもあります）をサポートし、2025-11-25 クライアントとの互換性を維持しています。Claude Desktop、Claude Code、Cursor、Windsurf、VS Code Copilot、および MCP 互換クライアントで動作します。

このサーバーは Jira Cloud、Jira Data Center、Confluence Cloud、Confluence Data Center（セルフホスト）をサポートしています。Atlassian Premium プランは必要ありません。

FastMCP、httpx、Pydantic を使用して構築されています。

プロトコルのサポート

• このサーバーは、MCP 2026-07-28 仕様（MCP 2.0 と呼ばれることもあります）を実装しています。
• 2025-11-25 クライアントとの互換性を維持しています。
• トランスポート：stdio（デフォルト）と streamable-http（リモートクライアントに推奨）。sse トランスポートも引き続き動作しますが、2026-07-28 仕様で非推奨となったため、サーバーは警告を出力します。
• サーバーはルート、サンプリング、ロギング、エリシテーション、リソースサブスクリプションを使用しません。2026-07-28 の非推奨化による影響はありません。
• FastMCP 4.x と MCP Python SDK 2.x を基盤に構築されています。

エラー結果

想定される失敗（404、401／403、読み取り専用による拒否、無効な引数）は、isError: true を持つツール結果として返されるため、MCP クライアントは、単に error という単語を含むだけの結果ではなく、失敗として認識できます。結果の本文は、API で発生した失敗の場合は status_code と body を含む、従来と同じ {"error": …, "hint": …} オブジェクトです。hint には修正方法が示されます。このオブジェクトが結果のテキストコンテンツです。厳格な MCP クライアントは isError が true の場合でも structuredContent をツールの出力スキーマに照らして検証し、エラーエンベロープはそのスキーマに一致しないため、structuredContent は設定されません。実際のバグは引き続きプロトコルレベルのツールエラーとして発生し、トレースバックとともにログに記録されます。

成功時、ツールは整形済み JSON をテキストコンテンツとして、その JSON オブジェクトを structuredContent として返します。2.0 より前の {"result": "<json string>"} ラッパーはなくなりました（複数ファイルのアップロードレスポンスのような、ペイロードが JSON 配列の場合は、structuredContent がオブジェクトでなければならないため、テキストのみが返されます）。ツールは outputSchema を公開しません。上流のフィールドは型指定なしでそのまま渡され、クライアントが必要とする場合は、@mcp.tool(...) の output_schema= を使ってツールごとに型付きスキーマをオプトインできます。

mcp-atlassian との関係

このプロジェクトは mcp-atlassian の代替ではなく、併用するものです。両方のサーバーを設定してください。

• mcp-atlassian が担当：課題、検索、トランジション、コメント、作業ログ、ページ、Confluence 検索
• mcp-atlassian-extended が担当：添付ファイル、アジャイル、ユーザー、フィールド、バージョン（API v2）、カレンダー、休暇

ツールの重複はありません。このサーバーは、mcp-atlassian にないツールのみを実装しています。

ワンクリックインストール

💡 ヒント： ほかの AI アシスタント（Claude Code、Windsurf、IntelliJ、Gemini CLI）については、**Atlassian Extended MCP インストールゲートウェイ**をご覧ください。

# with writes
claude mcp add atlassian-extended \
  -e JIRA_URL=https://your-company.atlassian.net -e [email protected] -e JIRA_API_TOKEN=your_api_token \
  -- uvx mcp-atlassian-extended
# locked read-only: write tools are not listed
claude mcp add atlassian-extended -e MCP_READ_ONLY=true \
  -e JIRA_URL=https://your-company.atlassian.net -e [email protected] -e JIRA_API_TOKEN=your_api_token \
  -- uvx mcp-atlassian-extended

{
  "mcpServers": {
    "atlassian-extended": {
      "command": "uvx",
      "args": ["mcp-atlassian-extended"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "your_api_token",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "[email protected]",
        "CONFLUENCE_API_TOKEN": "your_api_token",
        "MCP_READ_ONLY": "true"
      }
    }
  }
}

# with writes
gemini mcp add -s user -e JIRA_URL=https://your-company.atlassian.net -e [email protected] -e JIRA_API_TOKEN=your_api_token -e CONFLUENCE_URL=https://your-company.atlassian.net/wiki -e [email protected] -e CONFLUENCE_API_TOKEN=your_api_token atlassian-extended uvx mcp-atlassian-extended
# locked read-only
gemini mcp add -s user -e MCP_READ_ONLY=true -e JIRA_URL=https://your-company.atlassian.net -e [email protected] -e JIRA_API_TOKEN=your_api_token -e CONFLUENCE_URL=https://your-company.atlassian.net/wiki -e [email protected] -e CONFLUENCE_API_TOKEN=your_api_token atlassian-extended uvx mcp-atlassian-extended

{
  "servers": {
    "atlassian-extended": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-atlassian-extended"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "your_api_token",
        "MCP_READ_ONLY": "true"
      }
    }
  }
}

# with writes
codex mcp add atlassian-extended --env JIRA_URL=https://your-company.atlassian.net --env [email protected] --env JIRA_API_TOKEN=your_api_token -- uvx mcp-atlassian-extended
# locked read-only
codex mcp add atlassian-extended --env MCP_READ_ONLY=true --env JIRA_URL=https://your-company.atlassian.net --env [email protected] --env JIRA_API_TOKEN=your_api_token -- uvx mcp-atlassian-extended

uv pip install mcp-atlassian-extended

設定

Jira Cloud（Basic Auth）

Jira Data Center / Self-Hosted（ベアラートークン）

サーバーは、以下の環境変数を順に確認し、最初に一致したものを使用します。

1. JIRA_PAT
2. JIRA_PERSONAL_TOKEN
3. JIRA_TOKEN

Basic 認証が優先されます。JIRA_USERNAME と JIRA_API_TOKEN の両方を設定すると、サーバーは Basic 認証を使用し、個人アクセストークンを無視します。サーバーは、Cloud 用のペアが不完全な場合にのみ Bearer 認証を使用します。Bearer 認証を強制するには、JIRA_USERNAME と JIRA_API_TOKEN の設定を解除してください。

Confluence Cloud（Basic 認証）

Confluence Data Center / Self-Hosted（ベアラートークン）

サーバーは、以下の環境変数を順に確認し、最初に一致したものを使用します。

1. CONFLUENCE_PAT
2. CONFLUENCE_PERSONAL_TOKEN
3. CONFLUENCE_TOKEN

ここでも Basic 認証が優先されます。CONFLUENCE_USERNAME と CONFLUENCE_API_TOKEN は、すべての個人アクセストークンより優先されます。

Confluence のすべてのカレンダーツールには、Team Calendars アドオン（/rest/calendar-services/1.0/）が必要です。このアドオンがないインスタンスでは、すべてのカレンダーツールがアドオン名を示すヒント付きで 404 を返します。

オプション設定

互換性

ツール（22）

サーバーは、厳選された Jira および Confluence のワークフローガイドをMCP リソースとして公開します。

プロンプト（5）

サーバーはMCP プロンプトを提供します。これは、クライアントがスラッシュコマンドとして表示できる、再利用可能な複数ツールのワークフローテンプレートです。

使用例

課題の管理

"Create a story in PROJ with custom story points"
→ jira_create_issue(project_key="PROJ", summary="Add OAuth login", issue_type="Story",
    custom_fields={"customfield_10004": 5})

"Update a ticket's priority and add labels"
→ jira_update_issue(issue_key="PROJ-123", fields={"priority": {"name": "High"}, "labels": ["urgent"]})

"Create an epic and link related stories"
→ jira_create_issue(project_key="PROJ", summary="Q1 Auth Overhaul", issue_type="Epic")
→ jira_create_link(link_type="Relates", inward_issue="PROJ-100", outward_issue="PROJ-200")

添付ファイル

"List attachments on PROJ-123"
→ jira_get_attachments(issue_key="PROJ-123")

"Upload a screenshot to a ticket"
→ jira_upload_attachment(issue_key="PROJ-123", file_path="./screenshot.png")

"Download an attachment"
→ jira_download_attachment(content_url="https://jira.example.com/rest/api/2/attachment/content/456",
    save_path="report.pdf")  # lands in ./atlassian-downloads/report.pdf (or ATLASSIAN_DOWNLOAD_DIR)

アジャイルとスプリントの管理

"Get the current sprint for board 42"
→ jira_get_board(board_id=42) → jira_get_sprint(sprint_id=7)

"Move tickets into the next sprint"
→ jira_move_to_sprint(sprint_id=8, issue_keys=["PROJ-1", "PROJ-2", "PROJ-3"])

"View backlog for board 42"
→ jira_backlog(board_id=42, max_results=50)

バージョン管理

"List versions for project PROJ"
→ jira_get_project_versions(project_key="PROJ")

"Create a new release version"
→ jira_create_version(project_key="PROJ", name="v2.0.0", release_date="2026-04-01")

"Mark version as released"
→ jira_update_version(version_id="200", released=True)

休暇とスプリントのキャパシティ

"Who is out today?"
→ confluence_get_time_off(start_date="today", end_date="today", group_by_person=True)

"Get team time-off for the next two weeks"
→ confluence_get_time_off(start_date="today", end_date="+14d", group_by_person=True)

"Calculate sprint capacity accounting for PTO"
→ confluence_sprint_capacity(
    team_members=["Alice", "Bob", "Carol"],
    sprint_start="2025-03-03", sprint_end="2025-03-14")

セキュリティに関する考慮事項

• トークンのスコープ：Jira Cloud では、必要最小限の権限にスコープを設定した API トークンを使用してください。Data Center では、プロジェクトレベルのアクセス権を持つ PAT を使用してください。
• 読み取り専用モード：管理下の起動設定で MCP_READ_ONLY=true（または ATLASSIAN_READ_ONLY=true）を設定すると、サーバーはロックされた状態で起動します。10 個の書き込みツールと書き込みワークフロー用プロンプトは一覧に表示されず、呼び出すと「不明なツール」が返され、ガードはそれでも到達した書き込みを拒否します。実行時にロックが解除されることはありません。別の設定元からの false でも、.env ファイルでも、ツール引数でも解除できません。false／0／no／off／空以外の値を設定するとロックされ、--read-only でできるのはロックを有効にすることだけです。ロックの強度は起動設定次第です。ユーザーが編集できない場所（Claude Code の managed-mcp.json などの管理対象 MCP 設定、コンテナー、k8s または systemd の環境変数、あるいはホスト型 HTTP デプロイ）で設定してください。サーバーを自分で起動するユーザーは、その環境を制御できます。書き込みツールはすべて Jira のツールです。Confluence のツールはどちらのモードでも読み取り専用です。
• HTTP トランスポートの認証：HTTP トランスポート（--transport streamable-http／sse）では、設定済みの Atlassian 認証情報を使ってすべてのツールを提供するため、ポートに接続できるユーザーなら誰でも利用できます。そのため、ループバック以外のアドレスにバインドする場合は、共有ベアラートークンが必要です。ATLASSIAN_HTTP_BEARER_TOKEN（16 文字以上。openssl rand -hex 32 を使用）を設定し、クライアントから Authorization: Bearer <token> を送信してください。トークンは一定時間で比較されます。トークンが設定されていない場合、サーバーは 127.0.0.1／localhost／::1 以外のホストでの起動を拒否します。また、サーバーは HTTP リクエストの Host／Origin ヘッダーも検証（host_origin_protection="auto"）するため、DNS リバインディングを利用したページがループバックにバインドされたサーバーを操作することはできません。
• アップロード先ルートの制限：jira_upload_attachment は、アップロード先ルート（設定されている場合は ATLASSIAN_UPLOAD_DIR、それ以外の場合は作業ディレクトリ）内のファイルのみを読み取ります。包含チェックの前にパスを解決（シンボリックリンクをたどる）するため、ルート外を指すシンボリックリンクは拒否されます。ルート以下のドットファイルとドットディレクトリも拒否されます。サイズ上限は 100 MB です。
• ダウンロード先ディレクトリの制限：jira_download_attachment は、ダウンロード先ディレクトリ（ATLASSIAN_DOWNLOAD_DIR。デフォルトは ./atlassian-downloads/ で、初回使用時に作成）内にのみ書き込みます。save_path にはファイル名のみを指定してください。ディレクトリ、絶対パス、ドットファイルは拒否され、黙って除去されることはありません。既存のファイルは上書きされません。数値のサフィックス -1、-2 が追加され、最終的なパスが返されます。ダウンロードした本文のサイズ上限は、アップロード上限と同じ 100 MB です。プロジェクトの .gitignore に atlassian-downloads/ を追加してください。
• デスクトップクライアントに関する注意：Claude Desktop などのクライアントは、作業ディレクトリを / または $HOME にして stdio サーバーを起動します。そのため、ファイルシステムの大部分がアップロード先ルートになります（ドットファイルを除く）。このようなクライアントでは、ATLASSIAN_UPLOAD_DIR（必要に応じて ATLASSIAN_DOWNLOAD_DIR も）を明示的に設定してください。
• 移行（0.11 → 0.12）：アップロードは ATLASSIAN_UPLOAD_DIR（デフォルト：サーバーの作業ディレクトリ）内に制限され、ドットファイルは拒否されるようになりました。クライアントから ~/Downloads をアップロードする場合は、ATLASSIAN_UPLOAD_DIR=~/Downloads を設定してください。ダウンロード先は作業ディレクトリではなく ./atlassian-downloads/（または ATLASSIAN_DOWNLOAD_DIR）になりました。save_path に指定できるのはファイル名のみで、既存ファイルは上書きされません。
• ダウンロード URL の検証：サーバーは SSRF を防ぐため、添付ファイルのダウンロード URL をそれぞれ、設定された Jira URL のドメインと照合します。
• SSL 検証：サーバーはデフォルトで Jira と Confluence の SSL 検証を有効にします。信頼できるネットワーク内の自己署名証明書を使用する場合に限り、無効にしてください。
• MCP ツールのアノテーション：各ツールは、クライアント側の権限確認プロンプト用に readOnlyHint、destructiveHint、idempotentHint を宣言します。
• 認証情報の保存なし：サーバーは起動時に環境変数からトークンを読み込みます。トークンを保存することはありません。

レート制限と権限

レート制限

Jira Cloud ではユーザーごとにレート制限が適用されます。レート制限に達すると、ツールは待機するよう促すヒントとともに 429 エラーを返します。Confluence Calendar API の呼び出しは、Team Calendars プラグインのアーキテクチャにより、時間がかかることがあります。

必要な権限

CLI とトランスポートのオプション

# Default: stdio transport (for MCP clients)
uvx mcp-atlassian-extended

# HTTP transport. Use streamable-http for remote clients.
uvx mcp-atlassian-extended --transport streamable-http --port 9000

# A non-loopback HTTP bind requires a shared bearer token (>= 16 chars).
# Clients send it as "Authorization: Bearer <token>".
ATLASSIAN_HTTP_BEARER_TOKEN=$(openssl rand -hex 32) \
  uvx mcp-atlassian-extended --transport streamable-http --host 0.0.0.0 --port 9000

# sse still works, but the MCP 2026-07-28 spec deprecates it. The server prints a warning.
uvx mcp-atlassian-extended --transport sse --host 127.0.0.1 --port 8000

# CLI overrides for config
JIRA_PAT=xxx uvx mcp-atlassian-extended --jira-url https://jira.example.com --read-only

--jira-token、--jira-api-token、--confluence-token、--confluence-api-token フラグは引き続き機能しますが、非推奨となり、--help には表示されません。これらのフラグを使うと、トークンが ps やシェルの履歴から参照できる状態になります。代わりに JIRA_PAT／JIRA_API_TOKEN／CONFLUENCE_PAT／CONFLUENCE_API_TOKEN を設定してください。

サーバーは python-dotenv を使って、作業ディレクトリにある .env ファイルを自動的に読み込みます。

部分的な設定：Jira と Confluence は個別に設定できます。どちらか一方、または両方を設定してください。サーバーは常に 22 個すべてのツールを公開します。未設定の製品に対するツールを呼び出すと、設定すべき変数名を示す「未設定」エラーが返されます。サーバーは起動時に失敗しません。

Docker

最小構成の非 root イメージを提供しています。イメージはデフォルトで読み取り専用にロックされています（MCP_READ_ONLY=true）。書き込みを許可するには -e MCP_READ_ONLY=false を渡してください。

docker build -t mcp-atlassian-extended .
docker run --rm -i \
  -e JIRA_URL=https://your-company.atlassian.net \
  -e [email protected] -e JIRA_API_TOKEN=your_api_token \
  mcp-atlassian-extended

エントリーポイントは mcp-atlassian-extended コマンドです。イメージ名の後に CLI フラグを渡してください。公開ポートで HTTP トランスポートを使用する場合は、ATLASSIAN_HTTP_BEARER_TOKEN も設定し、--transport streamable-http --host 0.0.0.0 を指定して実行してください。

FAQ

MCP 2026-07-28 仕様（MCP 2.0）に対応していますか？

はい。MCP 2026-07-28 仕様（MCP 2.0）を実装しており、2025-11-25 クライアントとの互換性も維持しています。

対応しているトランスポートは何ですか？

stdio（デフォルト）と streamable-http（リモートクライアントに推奨）に対応しています。sse トランスポートも引き続き動作しますが、2026-07-28 仕様では非推奨となっています。

アシスタントが何も変更できないように、mcp-atlassian-extended を読み取り専用で実行できますか？

はい。MCP_READ_ONLY=true（または ATLASSIAN_READ_ONLY=true）を設定して起動してください。10 個の書き込みツールと、書き込みワークフロー用のプロンプトは一覧に表示されなくなるため、モデルからは見えません。これらを呼び出すと「不明なツール」が返され、プロセスの実行中に書き込みを再び有効にする方法はありません。管理対象の MCP 設定、コンテナーや systemd の環境変数、ホスト型のデプロイなど、自分で管理する起動設定で変数を設定してください。ユーザーが自分でサーバーを起動する場合、この変数を設定せずに起動できるためです。

セルフホストの Jira と Confluence で動作しますか？

はい。Jira Cloud、Jira Data Center、Confluence Cloud、Confluence Data Center に対応しています。Jira REST API v2 を使用しており、Cloud と Server／Data Center の両方で動作します。

必要な権限とトークンのスコープは何ですか？

Jira API トークン（Cloud）または個人用アクセストークン（Data Center）が必要です。各操作には、対応する Jira 権限が必要です。必要な権限を参照してください。

mcp-atlassian を置き換えるものですか？

いいえ。mcp-atlassian と併用でき、ツールの重複はありません。mcp-atlassian はコアの検索機能と CRUD を担います。このサーバーは添付ファイル、アジャイルボード、バージョン、カレンダーを追加します。

Confluence ツールにはアドオンが必要ですか？

はい。3 つの Confluence カレンダーツールには Team Calendars アドオンが必要です。アドオンがない場合は、アドオン名を示すヒントとともに 404 が返されます。

ツールはいくつ提供されますか？

Jira と Confluence 向けに、22 個のツール、15 個のリソース、5 個のプロンプトを提供します。

関連する MCP サーバー

• mcp-gitlab — GitLab との連携（83 個のツール、7 個のリソース、6 個のプロンプト）
• mcp-coda — Coda との連携（53 個のツール、12 個のリソース、5 個のプロンプト）
• mcp-argocd — Argo CD との連携（37 個のツール、7 個のリソース、7 個のプロンプト）

クレジット

sooperset による mcp-atlassian から着想を得ています。アーキテクチャとパターンは、同様の規約に従っています。

開発

git clone https://github.com/vish288/mcp-atlassian-extended.git
cd mcp-atlassian-extended
uv sync --all-extras

uv run pytest --cov
uv run ruff check .
uv run ruff format --check .

ライセンス

MIT