atlassian-mcp

Model Context Protocol (MCP) サーバー for 自己ホスト型 Jira (Server / Data Center) および自己ホスト型 Bitbucket (Server / Data Center)。チケット、プルリクエスト、レビュースレッド、git コンテキストに関する自然言語ワークフローのためのツールを提供します。

注: このサーバーは自己ホスト型インスタンスのみをサポートしています。Jira Cloud と Bitbucket Cloud は異なる API を使用するため、サポートされていません。

ツール

ワークフロー

Git

Jira

Bitbucket

自然言語の例

• 「何に取り組んでいますか？」 → get_dev_context

• 「FOO-123 のブランチを作成」 → start_work

• 「これをリリース / マージしてチケットをクローズ」 → complete_work

• 「レビュー待ちの自分の PR を表示」 → bitbucket_search に mine=true を指定

• 「このリポジトリの feature/ABC-123 からのオープン PR を一覧表示」 → bitbucket_search に fromBranch を指定

• 「PR 42 の完全な概要を教えて」 → bitbucket_get_pr

• 「現在のブランチから master への PR を開く」 → bitbucket_mutate に create を指定

• 「PR 42 を承認 / マージ / 却下」 → bitbucket_mutate に action を指定

• 「PR 42 のコメント 123 に返信」 → bitbucket_comment に commentId=123 を指定

• 「PR 42 のこのブロッカーを解決」 → bitbucket_comment に action=update, severity=BLOCKER, state=RESOLVED を指定

• 「PR のチェックリストタスクを一覧表示」 → bitbucket_pr_tasks に action=list を指定

• 「PAY プロジェクトで自分に割り当てられたバグを検索」 → jira_search に mine=true, issueType=Bug を指定

• 「現在のスプリントには何がありますか？」 → jira_search に resource=board_overview を指定

• 「FOO-123 を In Progress に移動」 → jira_mutate に transitionName="In Progress" を指定

• 「FOO-123 に 2h を記録」 → jira_mutate に worklog を指定

• 「PAY にバージョン 9.1.0 を作成」 → jira_version に action=create, projectKey=PAY, name=9.1.0 を指定

• 「PAY のリリースを一覧表示」 → jira_search に resource=versions, project=PAY を指定

• 「バージョン 12345 をリリース」 → jira_version に action=release, id=12345 を指定

• 「FOO-123 の修正バージョンを 9.1.0 に設定」 → jira_mutate に update.fixVersion=9.1.0 を指定

• 「エピック FOO-100 の下にタスクを作成」 → jira_mutate に create.issueType=Task, create.parent=FOO-100 を指定 (エピックを自動検出して Epic Link を設定)

• 「FOO-123 をエピック FOO-100 の下に移動」 → jira_mutate に update.epicLink=FOO-100 を指定

• 「エピックを作成」 → jira_mutate に create.issueType=Epic を指定 (エピック名はデフォルトで要約になります)

• 「ストーリーポイントを 5 に設定」 → jira_mutate に update.customFields={"Story Points": 5} を指定 — 値はプレーン (オプションラベル、ユーザー名、日付、ラベルの配列) で、サーバーがフィールドスキーマに従ってラップします

• 「このチケット / エピックには何を設定できますか？」 → jira_search resource=fields に issueKey=FOO-123 (編集画面) または project=FOO+issueType=Epic (作成画面) を指定: 必須フィールドと任意フィールド、値の形式、許可される値

Related MCP server: Bitbucket Server MCP

セットアップ

1. 設定ファイルを作成する

~/.atlassian-mcp.json を作成します:

{
  "$schema": "https://raw.githubusercontent.com/stubbedev/atlassian-mcp/master/atlassian-mcp.schema.json",
  "jira": {
    "url": "https://jira.example.com",
    "token": "your-jira-personal-access-token"
  },
  "bitbucket": {
    "url": "https://bitbucket.example.com",
    "token": "your-bitbucket-personal-access-token"
  }
}

$schema フィールドは任意ですが、エディターのオートコンプリートと検証が有効になります。

• projectKey はプロジェクトコードを意味します:

  • Jira の例: チケット PAY-123 内の PAY

  • Bitbucket の例: リポジトリパス ENG/payments-service 内のプロジェクト ENG

• より使いやすいエイリアスも使用できます:

  • Jira: project (projectKey のエイリアス)

  • Bitbucket: project と repo (projectKey と repoSlug のエイリアス)

• Bitbucket ツールでは、projectKey と repoSlug は通常、ローカルの origin リモートから自動検出されます。

• bitbucket_create_pull_request は現在のブランチから fromBranch も自動検出し、そのブランチに既存のオープン PR がある場合はそれを返します。

• Jira のプロジェクトスコープの呼び出しは projectKey を受け付け、指定すると最もよく機能します。

• projectKey が Jira の課題作成 / タイプ検索で省略された場合、サーバーは現在のブランチのチケットキーから推測を試み、表示されているプロジェクトが 1 つだけの場合は自動選択にフォールバックし、それ以外の場合は番号付きプロジェクト一覧を返して選択させます。

または、環境変数 (またはこのディレクトリ内の .env ファイル) を使用します:

JIRA_URL=https://jira.example.com
JIRA_ACCESS_TOKEN=your-jira-personal-access-token
BITBUCKET_URL=https://bitbucket.example.com
BITBUCKET_ACCESS_TOKEN=your-bitbucket-personal-access-token

設定は次の順序で解決されます: --config <path> CLI 引数 → ATLASSIAN_MCP_CONFIG 環境変数 → ~/.atlassian-mcp.json → $XDG_CONFIG_HOME/atlassian-mcp/config.json (デフォルト ~/.config/atlassian-mcp/config.json) → cwd 内の .atlassian-mcp.json → 環境変数。

2. AI ツールに接続する

クローンやビルドは不要です — npx @stubbedev/atlassian-mcp@latest をツールに指定するだけで、自動的にインストールされて実行されます。

注: --prefer-online は一部のクライアントで MCP の起動を壊す可能性があります。コマンドはシンプルに保ち、更新したい場合は以下の更新手順を使用してください。

Claude Code

claude mcp add atlassian -- npx -y @stubbedev/atlassian-mcp@latest --config ~/.atlassian-mcp.json

Cursor

~/.cursor/mcp.json (グローバル) または .cursor/mcp.json (プロジェクトのみ) に追加します:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/Users/you/.atlassian-mcp.json"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json に追加します:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/Users/you/.atlassian-mcp.json"]
    }
  }
}

Zed

~/.config/zed/settings.json に追加します:

{
  "context_servers": {
    "atlassian": {
      "command": {
        "path": "npx",
        "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"]
      }
    }
  }
}

OpenCode

プロジェクトルートの opencode.json (グローバルなら ~/.config/opencode/opencode.json) に追加します:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "atlassian": {
      "type": "local",
      "command": ["npx", "-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"]
    }
  }
}

Codex CLI

~/.codex/config.yaml に追加します:

mcpServers:
  atlassian:
    command: npx
    args:
      - -y
      - @stubbedev/atlassian-mcp@latest
      - --config
      - /home/you/.atlassian-mcp.json

その他の MCP 互換ツール

MCP をサポートするほとんどのツールは同じ JSON 形式を受け付けます。コマンドとして npx を使用し、引数に ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/path/to/config.json"] を指定します。

既存インストールの更新

MCPクライアントが既に設定済みで、最新のパッケージバージョンを使いたい場合:

npx clear-npx-cache

その後、MCPクライアントを再起動してください。

npmを使わずにインストールする

サーバーは単一の静的Goバイナリです。上記のnpxの方法では、初回実行時にプラットフォーム向けのプレビルドバイナリをダウンロードします。以下の代替手段はNodeを完全にスキップします:

# Go toolchain — installs to $GOBIN / $GOPATH/bin
go install github.com/stubbedev/atlassian-mcp@latest

# Nix flake
nix run github:stubbedev/atlassian-mcp -- --config ~/.atlassian-mcp.json

次に、MCPクライアントのcommandをnpxの代わりに生成されたatlassian-mcpバイナリに向けます。これらのインストール経路では、ffmpeg/ffprobeがPATH上にある必要があります（またはATLASSIAN_MCP_FFMPEG_PATH / ATLASSIAN_MCP_FFPROBE_PATHを設定してください）。npmラッパーはこれらを自動的にバンドルします。

HTTPサーバーとして実行する（共有 / プロキシ背後）

デフォルトでは、サーバーはstdio経由でMCPを話します（エディタによって起動される、クライアントごとに1つのプロセス）。代わりに、多くのクライアントが共有する長時間稼働のStreamable HTTPサーバーとして実行することもできます。リバースプロキシの背後で役立ちます:

atlassian-mcp --http                 # binds 127.0.0.1:7337
atlassian-mcp --http 127.0.0.1:9000  # custom address
ATLASSIAN_MCP_HTTP=1 atlassian-mcp   # same, via env

• 単一のエンドポイントPOST /mcp（JSON-RPC）に加え、サーバー→クライアントのリクエスト（roots/list、聞き出し）を運ぶオプションのGET /mcp SSEストリームがあります。サーバーはステートフルです。initializeはセッションを作成し、Mcp-Session-Idヘッダーを返します。クライアントは以降のすべてのリクエストとSSEストリームでそのヘッダーを必ずエコーする必要があります。セッションIDが欠落・不明・期限切れのリクエストはHTTP 404を受け取るため、クライアントは再初期化します（標準的なMCPクライアントの動作）。接続された各クライアント/ワークツリーは分離されたセッションです。

• 認証: ループバックバインドではトークンは不要です。非ループバックアドレスへのバインドはATLASSIAN_MCP_HTTP_TOKENを必須とします（クライアントはAuthorization: Bearer …として送信）。それ以外の場合、サーバーは起動を拒否します。TLSはプロキシで終端してください。

• **GET /healthz**は、プロキシ/ロードバランサー向けの認証不要の生存確認プローブです（okを返します）。アイドルセッションは1時間後に破棄されます。

リポジトリコンテキストはサーバーの作業ディレクトリではなく、クライアントから取得されます。 リポジトリを必要とするツール（git_*ツール、get_dev_context、start_work、complete_work、およびBitbucketプロジェクト/リポジトリの自動検出）は、次の順序で解決します。明示的なrepoPath引数 → リクエストヘッダーで固定されたルート（下記参照） → クライアントのMCPワークスペースルート（サーバーはroots/listで問い合わせ、セッションごとにキャッシュし、notifications/roots/list_changedで更新） → プロセスのcwd（stdioのみ）。したがって、1つの共有HTTPサーバーで多数のワークツリーを処理できます。各クライアント自身のワークスペースがその呼び出しを決定します。セッションが複数のルート（複数のワークツリー）を公開する場合、repoPathなしのツールは最初のgitリポジトリルートを使用します。特定のワークツリーを対象にするには、repoPath（絶対パス、またはルートのいずれかに一致するワークツリー名/ベース名）を渡します。Bitbucketでは、projectKey+repoSlugを明示的に渡すとリポジトリ検出を完全にスキップします。リポジトリはサーバーのホストから到達可能である必要があります（gitツールはgitをローカルで実行します）。

リクエストヘッダーによるルートの固定（HTTP）。 作業ツリーを既に把握しているリバースプロキシやハーネスは、roots/listの往復をスキップして、サーバーに直接渡すことができます（クライアントがroots機能を一切通知していない場合でも機能します）。file:// URIまたは絶対パスを送信します（複数の場合はカンマ区切り。最初のgitリポジトリが優先されます）:

X-Mcp-Root: file:///srv/myrepo
X-Mcp-Roots: /srv/a, /srv/b

受け入れられるヘッダー名: X-Mcp-Roots、X-Mcp-Root、Mcp-Roots、Mcp-Root。ヘッダー値は権威を持ちます。roots/listよりも優先され、list_changed後も維持されます。

既に実行中のHTTPサーバーに対するクライアント設定（Claude Codeの例）:

claude mcp add --transport http atlassian http://127.0.0.1:7337/mcp

添付ファイルのデコードパイプライン

添付ファイルツール（jira_get_attachment、bitbucket_get_attachment）は、バイナリ添付ファイルをモデルが読み取り可能なコンテンツにデコードしてから返します:

自動保存されたファイルは、TTLと合計サイズのクォータによって定期的に削除されます。詳細は下記の環境変数の上書きを参照してください。

外部ツール（オプション）

画像およびPDFテキストのデコードは純Goで実装されているため、追加のものは必要ありません。純Go実装がない2つのパイプラインは外部バイナリを呼び出します:

• ffmpeg + ffprobe — 動画およびアニメーション画像のフレームサンプリング用です。npmラッパーはffmpeg-static / ffprobe-staticをバンドルし、それらのパスを注入するため、npxインストール経路では設定不要です。go install / Nix経路では、ffmpegをインストールするか（ffprobeも含まれます）、下記の環境変数を設定してください。

• pdftoppm（poppler）またはmutool（MuPDF） — 抽出可能なテキストがないスキャンPDFをラスタライズする場合にのみ必要です。どちらもPATHにない場合、そのようなPDFは代わりにディスクに保存されます。

環境変数の上書き

リリース（メンテナー向け）

このパッケージはnpmに@stubbedev/atlassian-mcpとして公開されています。

リリースにはセマンティックバージョニングを使用してください。ツールのインターフェースを破壊する変更は、<1.0.0の間はマイナーバージョンを上げるべきです（例: 0.0.x -> 0.1.0）。

v*タグがプッシュされると、.github/workflows/publish.ymlがGoバイナリを14のOS/アーキテクチャターゲット向けにクロスコンパイルし、GitHubリリースに添付して、npmラッパーを公開します（npmラッパーはインストール時に一致するバイナリをダウンロードします）。

リリースの流れ:

# choose one: patch | minor | major (also: npm run release:patch / :minor / :major)
npm version patch          # bumps package.json, commits, tags vX.Y.Z
git push origin HEAD --follow-tags

flake.nixはpackage.jsonからバージョンを読み取るため、Nixパッケージも同じバージョンアップに自動的に追従します。GitHub Actionsはプッシュされたタグからビルドおよび公開を行います。

• ワークフローはnpm Trusted Publisher（OIDC）用に構成されているため、NPM_TOKENシークレットは不要です

必要なnpm設定（1回限り）:

• npmパッケージ設定で、このGitHubリポジトリ/ワークフローをTrusted Publisherとして追加してください

個人アクセストークンの作成

Jira Server / Data Center

個人アクセストークンはJira 8.14以降でサポートされています。

1. Jiraインスタンスにログインします。

2. 右上隅にあるプロフィールアバターをクリックし、プロフィールを選択します。

3. 左側のサイドバーで個人アクセストークンをクリックします。

4. トークンを作成をクリックします。

5. トークンに名前を付け（例: atlassian-mcp）、必要に応じて有効期限を設定します。

6. 作成をクリックしてトークンをコピーします。トークンは一度だけ表示されます。

設定ファイルのjiraの下にあるtokenの値としてトークンを貼り付けます。

Jiraのバージョンが8.14より古い場合は、代わりにHTTP Basic Authを使用できます。ただし、このサーバーはBearerトークン（PAT）認証のみをサポートしています。

Bitbucket Server / Data Center

個人アクセストークンはBitbucket Server 5.5以降でサポートされています。

1. Bitbucketインスタンスにログインします。

2. 右上隅にあるプロフィールアバターをクリックし、アカウントの管理を選択します。

3. 左側のサイドバーのセキュリティの下にある個人アクセストークンをクリックします。

4. トークンを作成をクリックします。

5. トークンに名前を付けます（例: atlassian-mcp）。

6. 権限を設定します:

   • プロジェクト: 読み取り

   • リポジトリ: 読み取り + 書き込み（書き込みはプルリクエストの作成とコメントの追加に必要です）

7. 必要に応じて有効期限を設定します。

8. 作成をクリックしてトークンをコピーします。トークンは一度だけ表示されます。

設定ファイルのbitbucketの下にあるtokenの値としてトークンを貼り付けます。

開発

サーバーはリポジトリルートにある単一のGoモジュールです（src/ツリーはありません）。

# Build the binary
go build -o atlassian-mcp .

# Run it
./atlassian-mcp --config /path/to/config.json

# Vet + unit tests
go vet ./...
go test ./...

# Test the tool list
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | ./atlassian-mcp

# Quick release smoke check (build + tools/list validation)
npm run smoke