jira-mcp-server

hoibui/jira-mcp-server

3.2

If you are the rightful owner of jira-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server designed for downloading attachments from Jira issues, offering intelligent path detection and flexible storage options.

Tools
3
Resources
0
Prompts
0

Jira Attachments MCP Server

A Model Context Protocol (MCP) server for downloading attachments from Jira issues.

Features

  • List all attachments for a specific Jira issue
  • Download individual attachments by ID
  • Download all attachments from an issue at once
  • 🧠 Intelligent path detection - Automatically determines download paths from natural language
  • 🐳 Docker support - Run anywhere consistently with containerization
  • 📁 Flexible storage - Download to any location with volume mounts
  • ⚡ Context-aware - Smart folder organization based on file types and keywords
  • Uses Jira REST API v3

Installation

Option 1: Docker (Recommended)

  1. Build the Docker image:
cd jira-mcp-server
npm run docker:build
  1. Test the server:
npm run docker:test

Option 2: Local Development

  1. Navigate to the server directory:
cd jira-mcp-server
  1. Install dependencies:
npm install
  1. Build the server:
npm run build

Configuration

Environment Variables

Set up the following environment variables:

export JIRA_BASE_URL="https://your-domain.atlassian.net"
# or alternatively
export ATLASSIAN_BASE_URL="https://your-domain.atlassian.net"
export ATLASSIAN_USER_EMAIL="your-email@domain.com"
export ATLASSIAN_API_TOKEN="your-api-token"

MCP Configuration

Docker Configuration (Recommended)

Add this to your MCP configuration file (e.g., .mcp.json):

{
  "mcpServers": {
    "jira-attachments": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "ATLASSIAN_BASE_URL=https://your-domain.atlassian.net",
        "-e", "ATLASSIAN_USER_EMAIL=your-email@domain.com",
        "-e", "ATLASSIAN_API_TOKEN=your-api-token",
        "-v", "/Users/$(whoami)/Downloads/jira-attachments:/app/downloads",
        "-v", "$(pwd):/app/workspace",
        "-w", "/app/workspace",
        "jira-attachments-mcp:latest"
      ]
    }
  }
}
Local Configuration

For local development:

{
  "mcpServers": {
    "jira-attachments": {
      "command": "node",
      "args": ["/absolute/path/to/jira-mcp-server/dist/index.js"],
      "env": {
        "ATLASSIAN_BASE_URL": "https://your-domain.atlassian.net",
        "ATLASSIAN_USER_EMAIL": "your-email@domain.com",
        "ATLASSIAN_API_TOKEN": "your-api-token"
      }
    }
  }
}

Available Tools

list_jira_attachments

Lists all attachments for a specific Jira issue.

Parameters:

  • issueKey (required): The Jira issue key (e.g., "PROJ-123")

Example:

Please list all attachments for issue ET-123

download_jira_attachment

Downloads a specific attachment from a Jira issue with intelligent path detection.

Parameters:

  • issueKey (required): The Jira issue key (e.g., "PROJ-123")
  • attachmentId (required): The attachment ID to download
  • downloadPath (optional): Local path where to save the attachment
  • context (optional): Context for intelligent path detection (e.g., "design mockups", "bug screenshots")

Examples:

Download attachment ID 12345 from issue ET-123 for design review
Download attachment ID 67890 from ET-123 to ./custom-folder/

download_all_jira_attachments

Downloads all attachments from a Jira issue with intelligent path detection.

Parameters:

  • issueKey (required): The Jira issue key (e.g., "PROJ-123")
  • downloadPath (optional): Local path where to save the attachments
  • context (optional): Context for intelligent path detection

Examples:

Download all attachments from ET-123 for UI testing
Download all attachments from ET-123 to .claude/workflows/tickets

Usage Examples

🧠 Intelligent Path Detection

The server automatically determines the best download location based on your natural language:

# Design workflows
"Download design mockups from ET-123"
→ Automatically saves to: ./design-assets/

"Download UI screenshots from ET-123 for testing"
→ Automatically saves to: ./screenshots/

"Download API documentation images from ET-123"
→ Automatically saves to: ./docs/api/

# Project-specific paths
"Download React component designs from ET-123"
→ Automatically saves to: ./src/assets/

"Download mobile app wireframes from ET-123"
→ Automatically saves to: ./assets/images/

📁 Explicit Path Control

# Specify exact locations
"Download all attachments from ET-123 to .claude/workflows/tickets"
"Download all attachments from ET-123 to ./custom-folder/"
"Download all attachments from ET-123 to /Users/$(whoami)/Documents/project-assets"

📋 Basic Operations

  1. List attachments:

    Please list all attachments for issue ET-123

  2. Download with context:

    Download bug screenshots from ET-123 for documentation
Download presentation files from ET-123 for client meeting

🐳 Docker Usage

Quick Start

# Build the image
npm run docker:build

# Test the server
npm run docker:test

# Run with volume mounts
docker run -i --rm \
  -e ATLASSIAN_BASE_URL="https://your-domain.atlassian.net" \
  -e ATLASSIAN_USER_EMAIL="your-email@domain.com" \
  -e ATLASSIAN_API_TOKEN="your-api-token" \
  -v "$(pwd):/app/workspace" \
  -v "/Users/$(whoami)/Downloads/jira-attachments:/app/downloads" \
  -w "/app/workspace" \
  jira-attachments-mcp:latest

Volume Mount Examples

# Default downloads to ~/Downloads/jira-attachments/
-v "/Users/$(whoami)/Downloads/jira-attachments:/app/downloads"

# Project-specific assets
-v "/Users/$(whoami)/Documents/project-assets:/app/assets"

# Current project workspace
-v "$(pwd):/app/workspace"

Docker Compose

See for a complete setup example.

🧠 Intelligent Path Detection

The server features smart path detection that automatically chooses download locations based on context:

Smart Keywords

  • Design: design, mockup, wireframe, figma → ./design-assets/
  • Testing: bug, screenshot, test, qa → ./test-assets/ or ./screenshots/
  • Documentation: docs, api, spec → ./docs/api/ or ./docs/images/
  • Development: react, frontend, mobile → ./src/assets/ or ./assets/images/
  • Media: image, video, pdf → ./images/, ./videos/, ./documents/

See for comprehensive examples.

File Naming

Downloaded files are automatically prefixed with the issue key to avoid conflicts:

  • Format: {ISSUE_KEY}_{original_filename}
  • Example: ET-123_document.pdf

Requirements

Docker (Recommended)

  • Docker Engine 20.10+
  • Valid Jira API token with appropriate permissions
  • Access to the Jira instance and issues you want to download from

Local Development

  • Node.js 18+
  • Valid Jira API token with appropriate permissions
  • Access to the Jira instance and issues you want to download from

Authentication

The server uses HTTP Basic Authentication with:

  • Username: Your Atlassian account email
  • Password: Your Atlassian API token

To create an API token:

  1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
  2. Click "Create API token"
  3. Copy the generated token and use it as ATLASSIAN_API_TOKEN

Troubleshooting

Authentication Issues

Download Issues

  • Issue not found: Ensure the issue key exists and you have permission to view it
  • No attachments: The issue might not have any attachments
  • Download errors: Check file permissions and available disk space
  • Path not created: Verify volume mounts are correct in Docker

Docker Issues

  • Image not found: Run npm run docker:build to build the image
  • Permission errors: Check volume mount permissions
  • Network issues: Ensure Docker can access external networks

Path Detection

  • Unexpected path: Use more specific context keywords or explicit paths
  • Directory not created: Check write permissions in the target location

Security Notes

  • API tokens should be kept secure and not committed to version control
  • The server creates directories if they don't exist
  • Files are downloaded to the specified path without additional validation