Atlassian Attachments
MCP server for downloading Jira and Confluence Cloud attachments by attachment ID.
Ask AI about Atlassian Attachments
Powered by Claude Β· Grounded in docs
I know everything about Atlassian Attachments. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
MCP Atlassian Attachments
A Model Context Protocol (MCP) server for downloading Jira Cloud attachments by attachment ID to local disk.
Supplement to the official Atlassian MCP server. The official Atlassian MCP server covers search, issue management, and content operations but does not support downloading attachment files to 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.
Authentication
Scoped tokens are recommended to limit access to exactly the permissions needed.
Note: The granular
read:attachment:jirascope is not sufficient β Jira's attachment metadata endpoint (/rest/api/3/attachment/{id}) requiresread:jira-workto 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 the
read:jira-workscope, 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 \
ATLASSIAN_EMAIL=your.email@example.com \
ATLASSIAN_API_TOKEN=your-api-token \
npx -y @modelcontextprotocol/inspector uvx mcp-atlassian-attachments
From a local clone:
ATLASSIAN_SITE_URL=https://yourorg.atlassian.net \
ATLASSIAN_EMAIL=your.email@example.com \
ATLASSIAN_API_TOKEN=your-api-token \
npx -y @modelcontextprotocol/inspector 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="your.email@example.com"
export ATLASSIAN_API_TOKEN="your-api-token"
Config file (~/.config/mcp-atlassian-attachments/config.json):
{
"site_url": "https://yourorg.atlassian.net",
"email": "your.email@example.com",
"api_token": "your-api-token"
}
Tools
| Tool | Description | Required params |
|---|---|---|
download_jira_attachment | Download a Jira attachment by ID. | attachment_id, output_dir |
Common parameters
| 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. |
Output
The tool returns a JSON object:
{
"product": "jira",
"attachmentId": "439535",
"filename": "screenshot.png",
"mimeType": "image/png",
"size": 496724,
"path": "/your/output/dir/screenshot.png",
"sourceUrl": "https://yourorg.atlassian.net/rest/api/3/attachment/content/439535"
}
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": "your.email@example.com",
"ATLASSIAN_API_TOKEN": "your-api-token"
}
}
}
}
Security
ATLASSIAN_API_TOKENis never logged or included in error messages.- The computed
Authorizationheader is never exposed in tool output or errors. - File writes are confined to the provided
output_dir. - Filenames are sanitized to prevent path traversal.
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.
