Atlassian MCP Server Setup Guide

Atlassian MCP Server Setup Guide

This guide provides step-by-step instructions for configuring the Atlassian MCP (Model Context Protocol) server to enable Claude to interact with Jira and Confluence.

Table of Contents

• Prerequisites
• Getting API Tokens
• Environment Setup
• MCP Configuration
• Verification
• Troubleshooting
• Security Considerations

Prerequisites

Before setting up the Atlassian MCP server, ensure you have:

1. Docker installed and running

   • Verify with: docker --version
   • Docker must be able to pull images from ghcr.io

2. Atlassian account access

   • For Cloud: Account with access to your organization's Jira and Confluence
   • For Server/Data Center: Administrative access to generate personal access tokens

3. Claude Code CLI installed

   • The MCP server integrates with Claude Code for AI-assisted workflows

Getting API Tokens

Atlassian Cloud (Recommended)

API tokens are the standard authentication method for Atlassian Cloud products.

Step 1: Navigate to API Token Management

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Sign in with your Atlassian account

Step 2: Create a New API Token

1. Click Create API token
2. Enter a descriptive label (e.g., "Claude MCP Integration")
3. Click Create
4. Copy the token immediately - it will not be shown again

Step 3: Note Your Credentials

You will need:

• Email address: The email associated with your Atlassian account
• API token: The token you just created
• Instance URL: Your Atlassian Cloud URL (e.g., https://yourcompany.atlassian.net)

Important: The same API token works for both Jira and Confluence if they are on the same Atlassian Cloud instance.

Atlassian Server / Data Center

For self-hosted Atlassian products, use Personal Access Tokens (PATs).

Jira Server/Data Center:

1. Navigate to your Jira instance
2. Click your profile icon > Profile
3. Go to Personal Access Tokens
4. Click Create token
5. Set token name and expiry
6. Copy the generated token

Confluence Server/Data Center:

1. Navigate to your Confluence instance
2. Click your profile icon > Settings
3. Go to Personal Access Tokens
4. Click Create token
5. Set token name and expiry
6. Copy the generated token

Environment Setup

Step 1: Create Environment File

Create a .env.local file in your project root (or the directory where you will run Claude Code):

touch .env.local

Step 2: Configure Environment Variables

Add the following variables to .env.local based on your setup:

For Atlassian Cloud:

# Confluence Cloud Configuration
CONFLUENCE_URL=https://yourcompany.atlassian.net/wiki
CONFLUENCE_USERNAME=your.email@company.com
CONFLUENCE_API_TOKEN=your-api-token-here

# Jira Cloud Configuration
JIRA_URL=https://yourcompany.atlassian.net
JIRA_USERNAME=your.email@company.com
JIRA_API_TOKEN=your-api-token-here

# Optional: Limit to specific spaces/projects
# CONFLUENCE_SPACES_FILTER=DOCS,WIKI,ENG
# JIRA_PROJECTS_FILTER=PROJ,DEV,OPS

# Optional: Enable read-only mode (disables all write operations)
# READ_ONLY_MODE=true

For Atlassian Server/Data Center:

# Confluence Server Configuration
CONFLUENCE_URL=https://confluence.yourcompany.com
CONFLUENCE_PERSONAL_TOKEN=your-personal-access-token
CONFLUENCE_SSL_VERIFY=true  # Set to "false" for self-signed certificates

# Jira Server Configuration
JIRA_URL=https://jira.yourcompany.com
JIRA_PERSONAL_TOKEN=your-personal-access-token
JIRA_SSL_VERIFY=true  # Set to "false" for self-signed certificates

# Optional: Limit to specific spaces/projects
# CONFLUENCE_SPACES_FILTER=DOCS,WIKI
# JIRA_PROJECTS_FILTER=PROJ,DEV

# Optional: Enable read-only mode
# READ_ONLY_MODE=true

Step 3: Verify .gitignore

Ensure .env.local is in your .gitignore to prevent accidental credential exposure:

# Check if .env.local is ignored
grep -q "\.env\.local" .gitignore || echo ".env.local" >> .gitignore

MCP Configuration

Step 1: Create MCP Configuration File

Create or update .mcp.json in your project root:

{
  "mcpServers": {
    "atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        ".env.local",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ]
    }
  }
}

Step 2: Pull the Docker Image

Pre-pull the image to ensure it is available:

docker pull ghcr.io/sooperset/mcp-atlassian:latest

Configuration Options

Multiple Environment Files:

If you have separate environment files for different purposes:

{
  "mcpServers": {
    "atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        ".env.atlassian",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ]
    }
  }
}

Combining with Other MCP Servers:

{
  "mcpServers": {
    "atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        ".env.local",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    }
  }
}

Verification

Step 1: Test Docker Connectivity

Verify the container can start and read your environment:

docker run --rm --env-file .env.local ghcr.io/sooperset/mcp-atlassian:latest --help

Step 2: Test with Claude Code

Start Claude Code and verify the MCP server is recognized:

claude

Then ask Claude to list available MCP tools or perform a simple operation:

List the Jira projects I have access to.

Or:

Show me the recent pages in Confluence.

Step 3: Verify Specific Operations

Test Jira connectivity:

What issues are in project [YOUR_PROJECT_KEY]?

Test Confluence connectivity:

List pages in the [YOUR_SPACE_KEY] Confluence space.

Expected Behavior

When working correctly:

• Claude can list Jira projects and issues
• Claude can read and create Confluence pages
• Claude can search across both platforms
• Claude reports any permission errors clearly

Troubleshooting

Common Issues

Issue: "Authentication failed" or "401 Unauthorized"

Causes and solutions:

1. Invalid API token: Regenerate your API token from Atlassian
2. Wrong username: For Cloud, use your email address, not username
3. Token expired: Server/DC tokens may expire; create a new one
4. Wrong URL format:
   • Jira Cloud: https://yourcompany.atlassian.net
   • Confluence Cloud: https://yourcompany.atlassian.net/wiki

Issue: "Connection refused" or "Cannot reach host"

Causes and solutions:

1. Docker networking: Ensure Docker can reach external URLs
2. VPN required: Connect to VPN if accessing internal Atlassian Server
3. Firewall blocking: Check corporate firewall rules
4. Wrong URL: Verify the URL is accessible in your browser

Issue: "SSL certificate verify failed"

For self-signed certificates on Server/Data Center:

CONFLUENCE_SSL_VERIFY=false
JIRA_SSL_VERIFY=false

Issue: "Permission denied" when reading/writing

Causes and solutions:

1. Insufficient permissions: Your Atlassian account needs appropriate project/space permissions
2. Read-only mode enabled: Check if READ_ONLY_MODE=true is set
3. Space/project restrictions: Verify you have access to the specific space or project

Issue: Docker image not found

# Pull the latest image
docker pull ghcr.io/sooperset/mcp-atlassian:latest

# Verify it exists
docker images | grep mcp-atlassian

Issue: Environment file not found

Ensure the path in .mcp.json is correct:

• Use relative path from where Claude Code runs
• Or use absolute path: /Users/yourname/project/.env.local

Debug Mode

To see detailed logs, run the container manually:

docker run -it --rm --env-file .env.local ghcr.io/sooperset/mcp-atlassian:latest

Verifying Environment Variables

Check that your environment file is properly formatted:

# List all variables (redacted)
grep -E "^[A-Z_]+" .env.local | sed 's/=.*/=***/'

Expected output:

CONFLUENCE_URL=***
CONFLUENCE_USERNAME=***
CONFLUENCE_API_TOKEN=***
JIRA_URL=***
JIRA_USERNAME=***
JIRA_API_TOKEN=***

Security Considerations

Credential Protection

1. Never commit credentials: Ensure .env.local is in .gitignore
2. Use environment-specific files: Keep production and development credentials separate
3. Rotate tokens regularly: Set calendar reminders to rotate API tokens
4. Use minimal permissions: Only grant the Atlassian account permissions it needs

Read-Only Mode

For safer exploration or demo environments:

READ_ONLY_MODE=true

This prevents any write operations to Jira or Confluence.

Space and Project Filtering

Limit Claude's access to specific areas:

# Only access these Confluence spaces
CONFLUENCE_SPACES_FILTER=DOCS,PUBLIC

# Only access these Jira projects
JIRA_PROJECTS_FILTER=SUPPORT,DOCS

Audit Trail

All operations performed through the MCP server are:

• Logged in Atlassian's audit logs
• Associated with your Atlassian account
• Subject to your organization's compliance policies

Token Revocation

If you suspect a token has been compromised:

1. Go to Atlassian API Token Management
2. Click Revoke next to the compromised token
3. Create a new token
4. Update your .env.local file

Environment Variable Reference

Confluence Variables

Jira Variables

Global Variables

Quick Start Checklist

• Docker installed and running
• API token created at Atlassian
• .env.local created with credentials
• .env.local added to .gitignore
• .mcp.json created with Atlassian configuration
• Docker image pulled: docker pull ghcr.io/sooperset/mcp-atlassian:latest
• Connection tested with Claude Code

Additional Resources

• Atlassian API Token Documentation
• MCP Atlassian GitHub Repository
• Workflow Commands Reference - Commands that use Atlassian integration