How do I install Atlassian Attachments?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Atlassian Attachments need an API key?

The publisher lists these environment variables: ATLASSIAN_SITE_URL, ATLASSIAN_EMAIL, ATLASSIAN_API_TOKEN.

What transport does Atlassian Attachments use?

Atlassian Attachments runs locally over stdio.

When was Atlassian Attachments last checked?

Last checked 2026-11-09. MCP server for downloading, uploading, and deleting Jira Cloud attachments by ID.

Atlassian Attachments MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

uvx mcp-atlassian-attachments==0.3.0

Credentials from the publisher

ATLASSIAN_SITE_URL — Atlassian Cloud site URL, for example https://yourorg.atlassian.net. Must be HTTPS. Can also be set in ~/.config/mcp-atlassian-attachments/config.json.
ATLASSIAN_EMAIL — Email address used for Atlassian Cloud Basic auth. Can also be set in ~/.config/mcp-atlassian-attachments/config.json.
ATLASSIAN_API_TOKEN — Atlassian Cloud API token. Used as the password in Basic auth. Can also be set in ~/.config/mcp-atlassian-attachments/config.json.

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1ATLASSIAN_SITE_URL=<value> ATLASSIAN_EMAIL=<value> ATLASSIAN_API_TOKEN=<secret> claude mcp add io.github.alyiox-mcp-atlassian-attachments -- uvx mcp-atlassian-attachments==0.3.0

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.alyiox-mcp-atlassian-attachments": {4      "command": "uvx",5      "args": [6        "mcp-atlassian-attachments==0.3.0"7      ],8      "env": {9        "ATLASSIAN_SITE_URL": "<value>",10        "ATLASSIAN_EMAIL": "<value>",11        "ATLASSIAN_API_TOKEN": "<secret>"12      }13    }14  }15}

claude_desktop_config.json

Local · pypiPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

MCP Jira Attachments

A Model Context Protocol (MCP) server for downloading Jira Cloud attachments by attachment ID to local disk, and uploading local files as attachments to a Jira issue.

Supplement to the official Atlassian MCP server. The official Atlassian MCP server covers search, issue management, and content operations but does not move attachment files between Jira and local disk. This server fills that gap.

Requirements: Python 3.13+, an Atlassian Cloud account, and an API token with at least the read:jira-work scope. Uploading also needs write:jira-work.

Authentication

Scoped tokens are recommended to limit access to exactly the permissions needed.

Note: The granular read:attachment:jira scope is not sufficient — Jira's attachment metadata endpoint (/rest/api/3/attachment/{id}) requires read:jira-work to resolve issue-level permissions. A classic (unscoped) API token also works.

Create an API token

Go to id.atlassian.com/manage-profile/security/api-tokens
Click Create API token
Choose "Create API token with scopes" and select read:jira-work (add write:jira-work to upload), or choose "Classic API token" for full access
Copy the generated token

Quick start

The fastest way to try the server is with the MCP Inspector. Set the three required environment variables and run:

From the published package (no clone needed):

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

From a local clone:

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

Configuration

Set environment variables or create a config file. Environment variables take priority.

Environment variables:

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

Config file (~/.config/mcp-atlassian-attachments/config.json):

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

Tools

Tool	Description	Required params
`download_jira_attachment`	Download a Jira attachment by ID.	`attachment_id`, `output_dir`
`upload_jira_attachment`	Upload a local file as an attachment on a Jira issue.	`issue_key`, `file_path`
`get_jira_attachment_reference`	Resolve an existing attachment into an ADF media node.	`attachment_id`
`delete_jira_attachment`	Permanently delete an attachment by ID.	`attachment_id`

`download_jira_attachment`

Parameter	Type	Description
`attachment_id`	string	Jira attachment ID
`output_dir`	string	Local directory for the saved file. Created automatically if it does not exist.
`filename`	string (optional)	Override filename. Uses metadata filename when omitted.
`overwrite`	bool (optional)	Replace an existing file. Defaults to `false`.

Returns:

{
  "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`

Parameter	Type	Description
`issue_key`	string	Jira issue key or ID, for example `PROJ-123`
`file_path`	string	Path to the local file to upload. Must exist.
`filename`	string (optional)	Name to store in Jira. Uses the local filename when omitted.

Returns:

{
  "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"
}

Each call adds a new attachment; Jira does not replace a same-named file. Uploads larger than the site attachment size limit fail with a 413.

`get_jira_attachment_reference`

Parameter	Type	Description
`attachment_id`	string	Jira attachment ID

Read-only. Returns mediaId for an attachment that is already on an issue:

{
  "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"
}

After an upload you do not need this tool — upload_jira_attachment already returns mediaId, so embedding costs no extra call.

`delete_jira_attachment`

Parameter	Type	Description
`attachment_id`	string	Jira attachment ID to delete permanently

Needs write:jira-work. Metadata is read before the delete, so the result reports what was removed and a missing ID fails without attempting anything:

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

There is no undo. Jira deletes the file outright, and a second call to the same ID fails with 404.

Deleting does not clean up references. If the attachment was embedded in a description or comment, the ADF media node stays exactly where it was and becomes a dangling reference — verified against a live issue. Remove the node yourself if you delete a file that was referenced.

Referencing an attachment in a description or comment

Uploading a file attaches it, but nothing appears inline in the description or a comment. Rendering it requires an ADF media node — and that node identifies the file by its Media Services UUID, not by the numeric attachment ID:

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

No Jira attachment metadata endpoint exposes that UUID, which is why this server resolves it: GET /rest/api/3/attachment/content/{id} answers with a 303 to https://api.media.atlassian.com/file/{mediaId}/binary, so reading the Location header without following the redirect yields the UUID at no download cost. The UUID exists as soon as the file is attached — it does not depend on the attachment being referenced anywhere.

Both tools therefore return mediaId. Writing the node into the issue is deliberately left to a Jira content tool such as the official Atlassian MCP server, whose addCommentToJiraIssue and editJiraIssue accept contentFormat: "adf" — this server moves files and does not edit issue content:

upload_jira_attachment → take mediaId from the result
Post a comment with an ADF body wrapping a media node built from it:

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

For a description, read the existing ADF, append the node, and write the whole document back — PUT /rest/api/3/issue/{key} replaces the field rather than appending to it.

Notes:

A bare media node is not rendered; it must be wrapped in mediaSingle (single file), mediaGroup (file-card list), or mediaInline (inline chip).
collection is "" for Jira issue attachments.
Optional width/height on the media node set the intrinsic pixel size, and are only honoured inside mediaSingle.
mediaId is best-effort: if the redirect cannot be read it comes back null, and the upload itself still succeeds.

Simpler alternative: v2 wiki markup

The older v2 endpoints still accept wiki markup and convert it to ADF server-side, resolving the attachment by filename — so no media UUID is needed:

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

Jira stores that as a proper media node with the correct UUID filled in. Confirmed working on Jira Cloud as of August 2026.

Two behaviours to know about, both verified against a live issue:

Dimensions are a fixed placeholder, not the real ones. The conversion always writes width: 200, height: 183 regardless of the image — a 64x48 and an 8x8 PNG both came back as 200x183. !file|width=300! sets the width but leaves height at 183, so the aspect ratio is wrong unless you write the ADF yourself.
Duplicate filenames resolve to the oldest. With two attachments both named ambiguous.png, !ambiguous.png! resolved to the first one uploaded. Re-uploading under the same name to "update" an image will keep showing the old file.

Prefer mediaId when you want to be explicit: it is unambiguous with duplicate names, it lets you set true dimensions, it works with v3/ADF (which is what the official Atlassian MCP server writes), and it does not depend on a legacy path Atlassian may eventually retire.

MCP host configuration

Add the following to your MCP host's config file. The JSON is the same for Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json), and 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"
      }
    }
  }
}

Security

ATLASSIAN_API_TOKEN is never logged or included in error messages.
The computed Authorization header is never exposed in tool output or errors.
File writes are confined to the provided output_dir.
Filenames are sanitized to prevent path traversal, both on download and on the name sent to Jira.
Uploads read exactly the file at file_path and send nothing else.

Tests

uv run pytest tests/ -v

Roadmap

download_confluence_attachment_tool — Confluence Cloud uses a different API (/wiki/api/v2/) and a different identifier model. Planned for a future release.

License

MIT. See LICENSE.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Atlassian Attachments?

Does Atlassian Attachments need an API key?

What transport does Atlassian Attachments use?

When was Atlassian Attachments last checked?

Documentation

MCP Jira Attachments

Authentication

Create an API token

Quick start

Configuration

Tools

download_jira_attachment

upload_jira_attachment

get_jira_attachment_reference

delete_jira_attachment

Referencing an attachment in a description or comment

Simpler alternative: v2 wiki markup

MCP host configuration

Security

Tests

Roadmap

License

`download_jira_attachment`

`upload_jira_attachment`

`get_jira_attachment_reference`

`delete_jira_attachment`