Atlassian Attachments

MCP Jira 添付ファイル

Jira Cloud の添付ファイルを添付ファイル ID でローカルディスクにダウンロードし、ローカルファイルを Jira の課題に添付ファイルとしてアップロードするための Model Context Protocol (MCP) サーバーです。

Atlassian 公式 MCP サーバーを補完します。 Atlassian 公式 MCP サーバー は検索、課題管理、コンテンツ操作に対応していますが、Jira とローカルディスク間で添付ファイルを移動する機能はありません。このサーバーはその不足を補います。

要件： Python 3.13 以降、Atlassian Cloud アカウント、および少なくとも read:jira-work スコープを持つ API トークンが必要です。アップロードには write:jira-work も必要です。

認証

必要な権限だけにアクセスを制限するため、スコープ付きトークンをおすすめします。

注： 詳細な read:attachment:jira スコープだけでは不十分です。Jira の添付ファイルメタデータエンドポイント（/rest/api/3/attachment/{id}）で課題レベルの権限を確認するには、read:jira-work が必要です。従来型の（スコープなし）API トークンも使用できます。

API トークンを作成する

1. id.atlassian.com/manage-profile/security/api-tokens にアクセスします
2. Create API token をクリックします
3. "Create API token with scopes" を選択して read:jira-work を指定します（アップロードする場合は write:jira-work も追加します）。または、すべてのアクセス権限を持つ "Classic API token" を選択します
4. 生成されたトークンをコピーします

クイックスタート

サーバーを最も手早く試すには、MCP Inspector を使用します。必須の環境変数を3つ設定して実行します。

公開済みパッケージから（クローン不要）：

ATLASSIAN_SITE_URL=https://yourorg.atlassian.net \
[email protected] \
ATLASSIAN_API_TOKEN=your-api-token \
npx -y @modelcontextprotocol/inspector@latest uvx mcp-atlassian-attachments

ローカルクローンから：

ATLASSIAN_SITE_URL=https://yourorg.atlassian.net \
[email protected] \
ATLASSIAN_API_TOKEN=your-api-token \
npx -y @modelcontextprotocol/inspector@latest uv run mcp-atlassian-attachments

設定

環境変数を設定するか、設定ファイルを作成します。環境変数が優先されます。

環境変数：

export ATLASSIAN_SITE_URL="https://yourorg.atlassian.net"
export ATLASSIAN_EMAIL="[email protected]"
export ATLASSIAN_API_TOKEN="your-api-token"

設定ファイル（~/.config/mcp-atlassian-attachments/config.json）：

{
  "site_url": "https://yourorg.atlassian.net",
  "email": "[email protected]",
  "api_token": "your-api-token"
}

ツール

ツール	説明	必須パラメーター
download_jira_attachment	Jira の添付ファイルを ID でダウンロードします。	attachment_id、output_dir
upload_jira_attachment	ローカルファイルを Jira の課題に添付ファイルとしてアップロードします。	issue_key、file_path
get_jira_attachment_reference	既存の添付ファイルを ADF メディアノードに解決します。	attachment_id
delete_jira_attachment	添付ファイルを ID で完全に削除します。	attachment_id

download_jira_attachment

パラメーター	型	説明
attachment_id	string	Jira の添付ファイル ID
output_dir	string	ファイルの保存先となるローカルディレクトリです。存在しない場合は自動的に作成されます。
filename	string (optional)	ファイル名を上書きします。省略するとメタデータのファイル名を使用します。
overwrite	bool (optional)	既存のファイルを置き換えます。デフォルトは false です。

戻り値：

{
  "product": "jira",
  "attachmentId": "439535",
  "filename": "screenshot.png",
  "mimeType": "image/png",
  "size": 496724,
  "path": "/your/output/dir/screenshot.png",
  "attachmentUrl": "https://yourorg.atlassian.net/rest/api/3/attachment/content/439535"
}

upload_jira_attachment

パラメーター	型	説明
issue_key	string	Jira の課題キーまたは ID（例：PROJ-123）
file_path	string	アップロードするローカルファイルのパスです。ファイルが存在している必要があります。
filename	string (optional)	Jira に保存する名前です。省略するとローカルのファイル名を使用します。

戻り値：

{
  "product": "jira",
  "issueKey": "PROJ-123",
  "attachmentId": "600100",
  "filename": "report.png",
  "mimeType": "image/png",
  "size": 24581,
  "path": "/your/local/dir/report.png",
  "attachmentUrl": "https://yourorg.atlassian.net/rest/api/3/attachment/content/600100",
  "mediaId": "6df94659-caa7-4561-bbe3-6384ec534bba"
}

呼び出すたびに新しい添付ファイルが追加されます。同じ名前のファイルがあっても、Jira は置き換えません。サイトの添付ファイルサイズ上限を超えるアップロードは 413 エラーになります。

get_jira_attachment_reference

パラメーター	型	説明
attachment_id	string	Jira 添付ファイル ID

読み取り専用です。課題にすでに添付されているファイルの mediaId を返します。

{
  "product": "jira",
  "attachmentId": "439535",
  "filename": "screenshot.png",
  "mimeType": "image/png",
  "size": 496724,
  "attachmentUrl": "https://yourorg.atlassian.net/rest/api/3/attachment/content/439535",
  "mediaId": "6df94659-caa7-4561-bbe3-6384ec534bba"
}

アップロード後にこのツールを使う必要はありません。upload_jira_attachment がすでに mediaId を返すため、埋め込みのための追加呼び出しは不要です。

delete_jira_attachment

パラメーター	型	説明
attachment_id	string	完全に削除する Jira 添付ファイル ID

write:jira-work が必要です。削除前にメタデータを読み取るため、結果には削除した内容が報告され、存在しない ID の場合は何も試みることなく失敗します。

{
  "product": "jira",
  "attachmentId": "481718",
  "filename": "delete-me.txt",
  "mimeType": "text/plain",
  "size": 31,
  "deleted": true
}

元に戻すことはできません。 Jira はファイルを完全に削除し、同じ ID に対する2回目の呼び出しは 404 で失敗します。

削除しても参照はクリーンアップされません。 添付ファイルが説明やコメントに埋め込まれていた場合、ADF メディアノードはそのまま残り、参照先のない状態になります。これは実際の課題で確認済みです。参照されているファイルを削除する場合は、ノードを自分で削除してください。

説明やコメントで添付ファイルを参照する

ファイルをアップロードすると添付されますが、説明やコメント内にはインラインで表示されません。表示するには ADF のメディアノードが必要です。このノードは数値の添付ファイル ID ではなく、ファイルの Media Services UUID で識別します。

{
  "type": "mediaSingle",
  "attrs": { "layout": "center" },
  "content": [
    {
      "type": "media",
      "attrs": {
        "type": "file",
        "id": "6df94659-caa7-4561-bbe3-6384ec534bba",
        "collection": "",
        "alt": "report.png"
      }
    }
  ]
}

Jira の添付ファイルメタデータエンドポイントではこの UUID を取得できないため、このサーバーが解決します。GET /rest/api/3/attachment/content/{id} は https://api.media.atlassian.com/file/{mediaId}/binary への 303 を返すため、リダイレクトをたどらずに Location ヘッダーを読み取れば、ダウンロードせずに UUID を取得できます。UUID はファイルが添付された時点で存在し、添付ファイルがどこかで参照されているかどうかには依存しません。

そのため、どちらのツールも mediaId を返します。課題へのノードの書き込みは、contentFormat: "adf" を受け付ける公式 Atlassian MCP サーバーなどの Jira コンテンツツールに意図的に任せています。このサーバーはファイルを移動しますが、課題の内容は編集しません。

1. upload_jira_attachment → 結果から mediaId を取得します
2. そこから作成したメディアノードをラップした ADF 本文でコメントを投稿します。

{
  "version": 1,
  "type": "doc",
  "content": [
    { "type": "paragraph", "content": [{ "type": "text", "text": "Latest run:" }] },
    { "type": "mediaSingle", "attrs": { "layout": "center" }, "content": [ "...the media node..." ] }
  ]
}

説明の場合は、既存の ADF を読み取り、ノードを追加して、ドキュメント全体を書き戻します。PUT /rest/api/3/issue/{key} はフィールドに追記するのではなく、置き換えます。

注意事項：

• media ノードだけでは表示されません。mediaSingle（単一ファイル）、mediaGroup（ファイルカードのリスト）、または mediaInline（インラインチップ）でラップする必要があります。
• Jira の課題添付ファイルでは、collection は "" です。
• メディアノードの width／height は省略可能で、固有のピクセルサイズを設定します。この値が反映されるのは mediaSingle 内だけです。
• mediaId はベストエフォートです。リダイレクトを読み取れない場合は null が返されますが、アップロード自体は成功します。

よりシンプルな代替手段：v2 wiki マークアップ

古い v2 エンドポイントでは、引き続き wiki マークアップを受け付け、サーバー側で ADF に変換します。添付ファイルはファイル名で解決されるため、メディア UUID は不要です。

POST /rest/api/2/issue/PROJ-123/comment
{ "body": "See attached: !report.png|thumbnail!" }

Jira はこれを、正しい UUID が設定された media ノードとして保存します。2026 年 8 月時点で Jira Cloud での動作を確認済みです。

稼働中の課題で確認した、知っておくべき動作が 2 つあります。

• 実際の寸法ではなく、固定のプレースホルダーが使われます。 画像にかかわらず、変換時には常に width: 200, height: 183 が書き込まれます。64x48 と 8x8 の PNG は、どちらも 200x183 で返されました。!file|width=300! は幅を設定しますが、高さは 183 のままなので、ADF を自分で記述しない限りアスペクト比が崩れます。
• 同じファイル名が複数ある場合、最も古いファイルが解決されます。 ambiguous.png という名前の添付ファイルが 2 つある場合、!ambiguous.png! は最初にアップロードされたファイルを解決しました。画像を「更新」するために同じ名前で再アップロードしても、古いファイルが表示され続けます。

明示的に指定したい場合は mediaId を優先してください。同名ファイルがあっても曖昧にならず、実際の寸法を設定でき、v3/ADF（公式 Atlassian MCP サーバーが書き込む形式）でも動作し、Atlassian が将来的に廃止する可能性のあるレガシーパスにも依存しません。

MCP ホストの設定

次の内容を MCP ホストの設定ファイルに追加します。JSON は Cursor（.cursor/mcp.json）、Claude Desktop（claude_desktop_config.json）、Claude Code（.claude.json）で共通です。

{
  "mcpServers": {
    "atlassian": {
      "command": "uvx",
      "args": ["mcp-atlassian-attachments"],
      "env": {
        "ATLASSIAN_SITE_URL": "https://yourorg.atlassian.net",
        "ATLASSIAN_EMAIL": "[email protected]",
        "ATLASSIAN_API_TOKEN": "your-api-token"
      }
    }
  }
}

セキュリティ

• ATLASSIAN_API_TOKEN がログに記録されたり、エラーメッセージに含まれたりすることはありません。
• 計算された Authorization ヘッダーが、ツールの出力やエラーに表示されることはありません。
• ファイルの書き込み先は、指定された output_dir 内に限定されます。
• ダウンロード時と Jira に送信する名前の両方で、パストラバーサルを防ぐためにファイル名がサニタイズされます。
• アップロードでは file_path のファイルだけを正確に読み取り、それ以外は送信しません。

テスト

uv run pytest tests/ -v

ロードマップ

• download_confluence_attachment_tool — Confluence Cloud では別の API（/wiki/api/v2/）と別の識別子モデルが使われます。今後のリリースで対応予定です。

ライセンス

MIT。詳細は LICENSE を参照してください。