MCP-Atlassian Project Details

Project Overview

MCP-Atlassian is a Model Context Protocol (MCP) based server designed specifically for Atlassian products (Confluence and Jira). This project allows AI assistants (such as Claude) to directly access and manipulate your Atlassian workspace data, enabling intelligent workflow management.

Project Basic Information

• Project Name: mcp-atlassian
• Developer: sooperset
• GitHub Address: https://github.com/sooperset/mcp-atlassian
• Deployment Method: Docker Container

Core Features

AI-Powered Intelligent Operations

The project supports various AI assistant-driven intelligent operations:

• 📝 Automated Jira Updates - "Update Jira from our meeting notes"
• 🔍 AI-Powered Confluence Search - "Find our OKR guide in Confluence and summarize it"
• 🐛 Intelligent Jira Issue Filtering - "Show urgent bugs in the PROJ project from last week"
• 📄 Content Creation and Management - "Create a technical design document for the XYZ feature"

Product Compatibility Support

Product	Deployment Type	Support Status
Confluence	Cloud	✅ Fully Supported
Confluence	Server/Data Center	✅ Supported (Version 6.0+)
Jira	Cloud	✅ Fully Supported
Jira	Server/Data Center	✅ Supported (Version 8.14+)

Installation and Configuration

Prerequisites

• Docker Environment
• Atlassian API Token (Cloud) or Personal Access Token (Server/Data Center)

Obtaining Authentication Tokens

Atlassian Cloud:

1. Visit https://id.atlassian.com/manage-profile/security/api-tokens
2. Click "Create API token", name it, and copy the token

Server/Data Center:

1. Go to Profile → Personal Access Tokens
2. Click "Create token", set the expiration time, and copy the token

Docker Image Retrieval

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

IDE Integration Configuration

Claude Desktop Configuration

Configuration file location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Method 1: Directly Passing Variables

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_USERNAME", 
        "-e", "CONFLUENCE_API_TOKEN",
        "-e", "JIRA_URL",
        "-e", "JIRA_USERNAME",
        "-e", "JIRA_API_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_confluence_api_token",
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com", 
        "JIRA_API_TOKEN": "your_jira_api_token"
      }
    }
  }
}

Method 2: Using an Environment File

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

Server/Data Center Configuration

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i", 
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_PERSONAL_TOKEN",
        "-e", "CONFLUENCE_SSL_VERIFY",
        "-e", "JIRA_URL", 
        "-e", "JIRA_PERSONAL_TOKEN",
        "-e", "JIRA_SSL_VERIFY",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://confluence.your-company.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your_confluence_pat",
        "CONFLUENCE_SSL_VERIFY": "false",
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_PERSONAL_TOKEN": "your_jira_pat", 
        "JIRA_SSL_VERIFY": "false"
      }
    }
  }
}

Environment Variable Description

Common environment variables:

• CONFLUENCE_SPACES_FILTER: Filter by space key (e.g., "DEV,TEAM,DOC")
• JIRA_PROJECTS_FILTER: Filter by project key (e.g., "PROJ,DEV,SUPPORT")
• READ_ONLY_MODE: Set to "true" to disable write operations
• MCP_VERBOSE: Set to "true" to enable verbose logging
• ENABLED_TOOLS: Comma-separated list of tool names

Available Tool Functions

Confluence Tools

Tool Name	Function Description
confluence_search	Search Confluence content using CQL
confluence_get_page	Get specific page content
confluence_get_page_children	Get page child pages
confluence_get_page_ancestors	Get page parent pages
confluence_get_comments	Get page comments
confluence_create_page	Create a new page
confluence_update_page	Update an existing page
confluence_delete_page	Delete a page
confluence_get_labels	Get labels
confluence_add_label	Add a label

Jira Tools

Tool Name	Function Description
jira_get_issue	Get specific issue details
jira_search	Search issues using JQL
jira_get_project_issues	Get project issues
jira_get_epic_issues	Get epic issues
jira_create_issue	Create a new issue
jira_batch_create_issues	Create issues in batch
jira_update_issue	Update an existing issue
jira_delete_issue	Delete an issue
jira_get_transitions	Get issue status transitions
jira_transition_issue	Transition issue status
jira_add_comment	Add a comment
jira_add_worklog	Add a worklog
jira_get_worklog	Get worklogs
jira_download_attachments	Download attachments
jira_link_to_epic	Link to an epic
jira_get_agile_boards	Get agile boards
jira_get_board_issues	Get board issues
jira_get_sprints_from_board	Get sprints from a board
jira_get_sprint_issues	Get sprint issues
jira_create_sprint	Create a sprint
jira_update_sprint	Update a sprint
jira_get_issue_link_types	Get issue link types
jira_create_issue_link	Create an issue link
jira_remove_issue_link	Remove an issue link

Note: Tools marked with * are only available on Jira Cloud

Access Control

Tool Filtering

Use the --enabled-tools flag or the ENABLED_TOOLS environment variable to specify available tools:

# Via environment variable
ENABLED_TOOLS="confluence_search,jira_get_issue,jira_search"

# Or via command-line flag
docker run ... --enabled-tools "confluence_search,jira_get_issue,jira_search" ...

Read/Write Control

Tools are divided into read and write operations. When READ_ONLY_MODE is enabled, only read operations are available, regardless of the ENABLED_TOOLS setting.

Troubleshooting

Common Issue Resolution

Authentication Failure:

• Cloud: Check the API token (not the account password)
• Server/Data Center: Verify the personal access token is valid and not expired
• Older Confluence Server: May need to use CONFLUENCE_USERNAME and CONFLUENCE_API_TOKEN (token is the password)

SSL Certificate Issues: For SSL errors in Server/Data Center deployments, set CONFLUENCE_SSL_VERIFY=false or JIRA_SSL_VERIFY=false

Permission Errors: Ensure the Atlassian account has sufficient permissions to access the relevant spaces/projects

Debugging Methods

Test with MCP Inspector:

npx @modelcontextprotocol/inspector uvx mcp-atlassian ...

View Logs:

# macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# Windows  
type %APPDATA%\Claude\logs\mcp*.log | more

Using SSE Transport

In addition to standard stdio transport, Server-Sent Events (SSE) are also supported:

1. Manually start the server in the terminal:

docker run --rm -p 9000:9000 \
  --env-file /path/to/your/.env \
  ghcr.io/sooperset/mcp-atlassian:latest \
  --transport sse --port 9000 -vv

2. Configure the IDE to connect to the running server:

{
  "mcpServers": {
    "mcp-atlassian-sse": {
      "url": "http://localhost:9000/sse"
    }
  }
}

Security Considerations

• Never share API tokens
• Keep .env files secure and private
• Review SECURITY.md for best practices

Technical Architecture

The project adopts Docker containerized deployment and communicates with AI assistants through the Model Context Protocol. It supports multiple transport methods (stdio and SSE), enabling flexible adaptation to different deployment environments and usage scenarios.

The project design considers the needs of enterprise-level applications, supports both cloud and privately deployed versions of Atlassian, and provides complete authentication, permission control, and security mechanisms.

---

Note: This is not an official Atlassian product, but an open-source project maintained by community developer sooperset.