A2atlassian

🏢 a2atlassian

Agent-to-Atlassian

AI エージェントに Jira と Confluence へのアクセスを提供します。認証情報を一度保存すれば、どこからでも作業できます。

Jira + Confluence · デフォルトで読み取り専用 · 事前設定済みの接続 · コンパクトな TSV 出力

クイックスタート · MCP ツール · セキュリティ · 比較 · セットアップ

---

Agent: "What's the status of PROJ-42? Add a comment with the progress update."
  ↓
a2atlassian → get issue, add comment, transition to In Progress
  ↓
Agent: "Done — PROJ-42 updated and moved to In Progress."

a2atlassian を選ぶ理由

既存の Atlassian MCP サーバー（Rovo、sooperset）では、Docker、.env ファイル、mcp-remote ブリッジが必要です。また、72 個ものツールをエージェントのコンテキストに読み込み、既知の問題によってエラーが発生しても通知されないことがあります。a2atlassian はこれらすべてを解決します。

• Docker 不要 — pip install a2atlassian を実行するだけです
• 事前設定済みの接続 — --register を使って .mcp.json にプロジェクトを定義すれば、エージェントはすぐに使えます
• デフォルトで読み取り専用 — 書き込みアクセスは接続ごとに明示的に有効にできます
• 接続のスコープ設定 — --scope でエージェントから見えるプロジェクトを制限できます
• コンパクトな出力 — リストは TSV（トークンを 30～60％削減）、単一のエンティティは JSON で出力します
• ツールの動的読み込み — 遅延ツールに対応する MCP クライアント（Claude Code など）は、必要に応じてツールを読み込むため、コンテキストを簡潔に保てます
• エラー情報の拡充 — 不正なフィールド名には候補を提示し、JQL の誤記を修正し、既知の問題を自動修正します
• シークレットは環境変数に保持 — 設定内の ${ATLASSIAN_TOKEN} は実行時にのみ展開されます

現在の対応範囲： Jira の全機能（課題、コメント、スプリント、ボード、作業ログ、リンク、バージョン、フィールド、ウォッチャー、プロジェクト）と、Confluence の主要機能（ページの CRUD、検索、メタデータのみの書き込み）に対応しています。

クイックスタート

# Recommended — installs globally as a CLI tool
uv tool install a2atlassian

# Or with pip
pip install a2atlassian

MCP サーバーとして使用（推奨）

Claude Code（事前設定済みの接続を使用）：

claude mcp add -s user a2atlassian -- uvx --from a2atlassian a2atlassian-mcp \
  --register myproject https://mysite.atlassian.net [email protected] '${ATLASSIAN_TOKEN}'

Claude Code（最小構成 — エージェントが必要に応じて login を呼び出します）：

claude mcp add -s user a2atlassian -- uvx --from a2atlassian a2atlassian-mcp

Claude Desktop / Cursor / 任意の MCP クライアント（.mcp.json）：

{
  "mcpServers": {
    "a2atlassian": {
      "command": "uvx",
      "args": [
        "--from", "a2atlassian", "a2atlassian-mcp",
        "--register", "myproject", "https://mysite.atlassian.net",
        "[email protected]", "${ATLASSIAN_TOKEN}"
      ],
      "env": {
        "ATLASSIAN_TOKEN": "your-api-token-here"
      }
    }
  }
}

複数のプロジェクト：

{
  "args": [
    "--from", "a2atlassian", "a2atlassian-mcp",
    "--register", "myproject", "https://mysite.atlassian.net", "[email protected]", "${TOKEN_A}",
    "--register", "personal", "https://personal.atlassian.net", "[email protected]", "${TOKEN_B}"
  ]
}

スコープ設定済みの接続（エージェントがアクセスできる保存済みプロジェクトを制限）：

{
  "args": ["--from", "a2atlassian", "a2atlassian-mcp", "--scope", "myproject"]
}

--register は一時的なインメモリ接続を作成します（プロセスの実行中のみ有効で、ファイルは書き込まれません）。--scope は表示対象となる保存済み接続を絞り込みます。どちらも影響範囲を制限します。

CLI として使用

# Save a connection (validates by calling /myself)
a2atlassian login -c myproject \
  --url https://mysite.atlassian.net \
  --email [email protected] \
  --token "$ATLASSIAN_TOKEN"

# Same, pulling the token from 1Password via `op`
a2atlassian login -c myproject \
  --url https://mysite.atlassian.net \
  --email [email protected] \
  --token "op://Personal/Atlassian/token"

# Enable writes
a2atlassian login -c myproject \
  --url https://mysite.atlassian.net \
  --email [email protected] \
  --token "$ATLASSIAN_TOKEN" \
  --no-read-only

# List / remove connections
a2atlassian connections
a2atlassian logout -c myproject

トークンには次の 3 つの形式を使用できます。リテラル値、${ENV_VAR} 参照、または op://vault/item/field（実行時に 1Password CLI で解決）。

MCP ツール

接続管理

ツール	説明
login	接続を保存します。最初に /myself を呼び出して検証します
logout	保存済みの接続を削除します
list_connections	接続を一覧表示します（シークレットは公開されません）

Jira — 読み取り

ツール	説明
jira_get_issue	キーで課題を取得 — 全フィールド、ステータス、担当者
jira_search	ページネーション対応の JQL 検索 — デフォルトではコンパクトな TSV 出力
jira_search_count	件数のみを取得する JQL — 「結果が膨大になりそうか？」を低コストで事前確認
jira_search_fields	名前からカスタムフィールド ID を確認
jira_get_field_options	選択／複数選択フィールドの許可値を一覧表示
jira_get_comments	課題のすべてのコメントを取得
jira_get_worklogs	課題のすべての作業ログを取得
jira_get_transitions	利用可能なステータス遷移を確認
jira_get_link_types	利用可能な課題リンクタイプを一覧表示
jira_get_watchers	課題のウォッチャーを一覧表示
jira_get_projects	接続からアクセスできるプロジェクトを一覧表示
jira_get_project_metadata	作成メタデータ（課題タイプ、必須フィールド）を取得
jira_get_user_profile	メールアドレス／accountId からユーザープロファイル全体を特定
jira_get_boards	プロジェクト内のアジャイルボードを一覧表示
jira_get_board_issues	ボード上の課題（ページネーション対応）
jira_get_sprints	ボード上のスプリントを一覧表示
jira_get_sprint_issues	スプリント内の課題（ページネーション対応）

Jira — 書き込み（読み書き可能な接続が必要）

ツール	説明
jira_create_issue	新しい課題を作成
jira_update_issue	既存の課題のフィールドを更新
jira_delete_issue	課題を削除
jira_transition_issue	課題を新しいステータスに移動
jira_add_comment	コメントを追加（Wiki マークアップ、API v2）
jira_edit_comment	既存のコメントを更新
jira_add_worklog	課題に作業時間を記録
jira_create_issue_link	2 つの課題をリンク
jira_remove_issue_link	課題リンクを削除
jira_set_watchers	課題のウォッチャー一覧を置き換え
jira_create_sprint	ボード上にスプリントを作成
jira_update_sprint	スプリントの状態／日付を更新
jira_add_issues_to_sprint	課題をスプリントに移動
jira_create_version	プロジェクトのバージョンを作成

Confluence — 読み取り

ツール	説明
confluence_get_page	ID でページを取得（本文ストレージ、バージョン、スペース）
confluence_get_page_children	ページの直接の子ページを一覧表示（ページネーション対応）
confluence_search	CQL 検索。一致ごとの行は最小限

Confluence — 書き込み（読み書き可能な接続が必要）

ツール	説明
confluence_upsert_pages	作成または更新を一括実行。省略時は本文を保持する仕様、ページごとのステータス、部分的な失敗の形式に対応
confluence_set_page_properties	メタデータのみを書き込み（page_width、絵文字、ラベル） — 本文やタイトルには物理的に変更を加えられません

出力形式

すべてのツールは format パラメーターを受け付けます。

形式	デフォルトの対象	説明
toon	リスト（検索、コメント）	ヘッダー付き TSV — 形は一度、データは多数。JSON よりトークンを 30～60% 削減
json	単一のエンティティ（get_issue）	メタデータエンベロープ付きの標準 JSON

リストの応答には、TOON に着想を得た、コンパクトな TSV 形式（ヘッダー行 + タブ区切りの値）を使用します。これは a2db が採用している方法と同じで、列名は一度だけ示され、その後は値だけが続きます。50 件の課題の検索結果では、通常 JSON と比べてトークンを 40～60% 節約できます。

TSV の例（検索結果）：

# search (23 results, 50ms, truncated: False)
key	summary	assignee	status
PROJ-142	Fix auth timeout	Alice Smith	In Progress
PROJ-141	Add search filters	Bob Jones	To Do

JSON の例（単一の課題）：

{
  "data": {"key": "PROJ-142", "fields": {"summary": "Fix auth timeout", ...}},
  "count": 1,
  "truncated": false,
  "time_ms": 85
}

エラーの補足情報

何かが失敗すると、a2atlassian はエージェントに対処方法を伝えます。

Field 'asignee' does not exist
Did you mean: assignee?

Connection 'myproject' is read-only.
Run: a2atlassian login -p myproject --read-only false

自動的に処理される特殊な仕様：

• 担当者には表示名が必要です（712020: のアカウント ID ではありません）。自動検出してヒントを表示します
• Parent フィールドはプレーン文字列である必要があります — {"key": "PROJ-14"} は通知なしで "PROJ-14" に正規化されます
• 課題タイプの変換は API でサポートされていません — Jira UI での明確な操作手順を提示します

セキュリティ

デフォルトで読み取り専用

すべての接続は読み取り専用で開始します。書き込みツールは実行前に接続フラグを確認します。

Connection 'myproject' is read-only.
Re-run 'a2atlassian login -p myproject --read-only false' to enable writes.

書き込みアクセスを制御するのは人間のオペレーターであり、エージェントではありません。

認証情報の保存

login で保存した接続は、TOML ファイルとして ~/.config/a2atlassian/connections/ に保存されます。

• ファイルの権限： 0600（所有者のみ読み取り／書き込み可能）
• ${ATLASSIAN_TOKEN} 構文 — 環境変数への参照はそのまま保存され、実行時に展開されます
• 出力にシークレットを含めない — list_connections に表示されるのはプロジェクト名、URL、モードのみで、トークンは表示されません
• 一時モード — --register を使うと、認証情報はメモリ内のみに保持され、ディスクには書き込まれません

接続のスコープ設定

--scope を使用すると、特定の MCP インスタンスがアクセスできる保存済み接続を制限できます。

# Project config — only myproject visible, even if other connections are saved
uvx --from a2atlassian a2atlassian-mcp --scope myproject

プロジェクトレベルの MCP 設定（.claude/mcp.json）はグローバル設定を上書きするため、各リポジトリからは独自の接続のみが見えます。

レート制限

Atlassian のレート制限（429）や一時的なサーバーエラー（500）に対して、指数バックオフを伴う組み込みの再試行機能を備えています。エラーを表示する前に、1 秒後と 3 秒後に 2 回再試行します。

比較

機能	a2atlassian	Rovo（公式）	sooperset/mcp-atlassian
セットアップ	pip install	OAuth + Docker	Docker + .env + mcp-remote
コンテキスト内のツール数	約35（必要に応じて読み込み）	約72	約72
接続管理	TOML + --register + --scope	セッションごとの OAuth	.env ファイル
複数プロジェクト対応	あり（スコープ設定可能）	なし	セットアップごとに .env が1つ
デフォルトで読み取り専用	あり（接続ごと）	なし	なし
出力形式	TSV + JSON	JSON	JSON
エラーの補足情報	フィールドの候補、癖への対処	一般的なエラー	一般的なエラー
癖への対処	自動修正（担当者、親）	文書化された回避策	文書化された回避策
レート制限	組み込みの再試行	なし	なし
CLI	あり	なし	なし
ライセンス	Apache 2.0	プロプライエタリ	MIT

ロードマップ

リリース済み： Jira の全機能（v0.3.0） · CommonMark + GFM との完全な互換性を備えた Confluence の主要機能 + Markdown からストレージ形式への変換（v0.4.0、v0.5.2） · 1Password の op:// トークン参照（v0.5.1） · Confluence のメタデータのみの書き込み + 省略時に本文を保持するセマンティクス（v0.5.2）。

次の予定： confluence_delete_page、Confluence のコメントと添付ファイル、Confluence 統合テストの経路。バックログは TODO.md をご覧ください。

環境別のセットアップ

ローカル（macOS / Linux）

# Recommended
uv tool install a2atlassian

# Or with pip
pip install a2atlassian

# CLI
a2atlassian login -p myproject --url https://mysite.atlassian.net --email [email protected] --token "$TOKEN"

# Or add as MCP server (see Quick Start)

CI / 自動化

uv tool install a2atlassian

# Pre-configured — no login needed
uvx --from a2atlassian a2atlassian-mcp --register ci https://mysite.atlassian.net [email protected] "${CI_ATLASSIAN_TOKEN}"

開発

make bootstrap   # Install deps + pnpm + git hooks
make check       # Lint + test + coverage-diff + security (full gate)
make test        # Tests with coverage
make lint        # agent-harness + jscpd + actionlint (never modifies files)
make fix         # Auto-fix + lint
make similar     # Advisory: report similarly-named functions/classes

リンター：ruff + ty（agent-harness 経由）、yamllint、jscpd（pnpm 経由のコピー＆ペースト検出）、actionlint（GitHub Actions のワークフロー）。各コミットで、pre-commit フックが agent-harness fix と lint を実行します。pnpm と actionlint は brew install pnpm actionlint でインストールしてください。

ライセンス

Apache 2.0

---

_{🏢 2025年より、エージェントを第一に考えた Atlassian アクセスを提供しています。}

_{Denis Tomilin が開発しました}