Model Context Protocol (MCP) server for Atlassian products (Confluence and Jira). This integration supports both Confluence & Jira Cloud and Server/Data Center deployments.

This is an enhanced fork of sooperset/mcp-atlassian with significant improvements and new capabilities:

• 📋 OpenSpec-Driven Development - Comprehensive specification system for structured change management and proposal-driven development workflow
• 🔧 Enhanced Testing Infrastructure - Robust test environment management with real API testing capabilities and comprehensive test coverage
• 🛠️ Development Tooling Suite - Extensive collection of scripts for OAuth setup, authentication testing, and live data validation
• 📊 Improved Error Handling - Advanced error diagnostics, retry mechanisms, and detailed logging throughout the application
• 🏗️ Organized Project Structure - Reorganized directory structure with dedicated spaces for development tools and specifications

This fork emphasizes:

• Developer Experience: Comprehensive tooling for easier development and testing
• Reliability: Enhanced error handling and retry mechanisms
• Maintainability: Structured change management through OpenSpec
• Testing: Real-world API testing capabilities
• Documentation: Complete development guides and specifications

This fork includes extensive development tooling not found in upstream:

• oauth_authorize.py - Complete OAuth authorization flow testing
• test_with_real_data.sh - Real API testing against live Atlassian instances
• test_auth_setup.py - Authentication method validation
• test_simple_auth.py - Basic authentication testing
• find_test_issues.py - Test data discovery and management
• Docker utilities - Build, save, and load scripts for development workflow

• Structured change proposals with validation workflows
• Comprehensive specifications for all capabilities
• Development guidelines and contribution standards
• Change management with approval workflows

mcp-atlassian/
├── openspec/                    # 🆕 Specification system
│   ├── AGENTS.md               # AI development guidelines
│   ├── specs/                  # Current capabilities documentation
│   └── changes/                # Proposed changes with validation
├── scripts/                     # 🆕 Development tools
│   ├── oauth_authorize.py      # OAuth testing utilities
│   ├── test_with_real_data.sh  # Live API testing
│   └── docker-*.sh            # Development Docker workflow
└── src/mcp_atlassian/          # Enhanced with improved error handling

Ask your AI assistant to:

• 📝 Automatic Jira Updates - "Update Jira from our meeting notes"
• 🔍 AI-Powered Confluence Search - "Find our OKR guide in Confluence and summarize it"
• 🐛 Smart Jira Issue Filtering - "Show me urgent bugs in PROJ project from last week"
• 📄 Content Creation & Management - "Create a tech design doc for XYZ feature"

MCP Atlassian supports three authentication methods:

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click Create API token, name it
3. Copy the token immediately

1. Go to your profile (avatar) → Profile → Personal Access Tokens
2. Click Create token, name it, set expiry
3. Copy the token immediately

1. Go to Atlassian Developer Console
2. Create an "OAuth 2.0 (3LO) integration" app
3. Configure Permissions (scopes) for Jira/Confluence
4. Set Callback URL (e.g., http://localhost:8080/callback)
5. Run setup wizard:

   docker run --rm -i \
     -p 8080:8080 \
     -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \
     ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v

6. Follow prompts for Client ID, Secret, URI, and Scope
7. Complete browser authorization
8. Add obtained credentials to .env or IDE config:
   • ATLASSIAN_OAUTH_CLOUD_ID (from wizard)
   • ATLASSIAN_OAUTH_CLIENT_ID
   • ATLASSIAN_OAUTH_CLIENT_SECRET
   • ATLASSIAN_OAUTH_REDIRECT_URI
   • ATLASSIAN_OAUTH_SCOPE

MCP Atlassian is distributed as a Docker image. This is the recommended way to run the server, especially for IDE integration. Ensure you have Docker installed.

# Pull Pre-built Image
docker pull ghcr.io/sooperset/mcp-atlassian:latest

MCP Atlassian is designed to be used with AI assistants through IDE integration.

There are two main approaches to configure the Docker container:

1. Passing Variables Directly (shown in examples below)
2. Using an Environment File with --env-file flag (shown in collapsible sections)

Method 1 (Passing Variables Directly):

{
  "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": "[email protected]",
        "CONFLUENCE_API_TOKEN": "your_confluence_api_token",
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "your_jira_api_token"
      }
    }
  }
}

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

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

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v", "<path_to_your_home>/.mcp-atlassian:/home/app/.mcp-atlassian",
        "-e", "JIRA_URL",
        "-e", "CONFLUENCE_URL",
        "-e", "ATLASSIAN_OAUTH_CLIENT_ID",
        "-e", "ATLASSIAN_OAUTH_CLIENT_SECRET",
        "-e", "ATLASSIAN_OAUTH_REDIRECT_URI",
        "-e", "ATLASSIAN_OAUTH_SCOPE",
        "-e", "ATLASSIAN_OAUTH_CLOUD_ID",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "ATLASSIAN_OAUTH_CLIENT_ID": "YOUR_OAUTH_APP_CLIENT_ID",
        "ATLASSIAN_OAUTH_CLIENT_SECRET": "YOUR_OAUTH_APP_CLIENT_SECRET",
        "ATLASSIAN_OAUTH_REDIRECT_URI": "http://localhost:8080/callback",
        "ATLASSIAN_OAUTH_SCOPE": "read:jira-work write:jira-work read:confluence-content.all write:confluence-content offline_access",
        "ATLASSIAN_OAUTH_CLOUD_ID": "YOUR_CLOUD_ID_FROM_SETUP_WIZARD"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "JIRA_URL",
        "-e", "CONFLUENCE_URL",
        "-e", "ATLASSIAN_OAUTH_CLOUD_ID",
        "-e", "ATLASSIAN_OAUTH_ACCESS_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "ATLASSIAN_OAUTH_CLOUD_ID": "YOUR_KNOWN_CLOUD_ID",
        "ATLASSIAN_OAUTH_ACCESS_TOKEN": "YOUR_PRE_EXISTING_OAUTH_ACCESS_TOKEN"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "... existing Confluence/Jira vars",
        "-e", "HTTP_PROXY",
        "-e", "HTTPS_PROXY",
        "-e", "NO_PROXY",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "... existing Confluence/Jira vars": "...",
        "HTTP_PROXY": "http://proxy.internal:8080",
        "HTTPS_PROXY": "http://proxy.internal:8080",
        "NO_PROXY": "localhost,.your-company.com"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_USERNAME",
        "-e", "CONFLUENCE_API_TOKEN",
        "-e", "CONFLUENCE_CUSTOM_HEADERS",
        "-e", "JIRA_URL",
        "-e", "JIRA_USERNAME",
        "-e", "JIRA_API_TOKEN",
        "-e", "JIRA_CUSTOM_HEADERS",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "[email protected]",
        "CONFLUENCE_API_TOKEN": "your_confluence_api_token",
        "CONFLUENCE_CUSTOM_HEADERS": "X-Confluence-Service=mcp-integration,X-Custom-Auth=confluence-token,X-ALB-Token=secret-token",
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "your_jira_api_token",
        "JIRA_CUSTOM_HEADERS": "X-Forwarded-User=service-account,X-Company-Service=mcp-atlassian,X-Jira-Client=mcp-integration"
      }
    }
  }
}

import asyncio
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

user_token = "user-specific-oauth-token"
user_cloud_id = "user-specific-cloud-id"

async def main():
    # Connect to streamable HTTP server with custom headers
    async with streamablehttp_client(
        "http://localhost:9000/mcp",
        headers={
            "Authorization": f"Bearer {user_token}",
            "X-Atlassian-Cloud-Id": user_cloud_id
        }
    ) as (read_stream, write_stream, _):
        # Create a session using the client streams
        async with ClientSession(read_stream, write_stream) as session:
            # Initialize the connection
            await session.initialize()

            # Example: Get a Jira issue
            result = await session.call_tool(
                "jira_get_issue",
                {"issue_key": "PROJ-123"}
            )
            print(result)

asyncio.run(main())

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_USERNAME",
        "-e", "CONFLUENCE_API_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "[email protected]",
        "CONFLUENCE_API_TOKEN": "your_api_token"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_PERSONAL_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://confluence.your-company.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your_personal_token"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "JIRA_URL",
        "-e", "JIRA_USERNAME",
        "-e", "JIRA_API_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "your_api_token"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "JIRA_URL",
        "-e", "JIRA_PERSONAL_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_PERSONAL_TOKEN": "your_personal_token"
      }
    }
  }
}

Instead of using stdio, you can run the server as a persistent HTTP service using either:

• sse (Server-Sent Events) transport at /sse endpoint
• streamable-http transport at /mcp endpoint (stateful or stateless)

Both transport types support single-user and multi-user authentication:

Authentication Options:

• Single-User: Use server-level authentication configured via environment variables
• Multi-User: Each user provides their own authentication:
  • Cloud: OAuth 2.0 Bearer tokens
  • Server/Data Center: Personal Access Tokens (PATs)

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

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

  # OR for stateless streamable-http transport
  docker run --rm -p 9000:9000 \
    --env-file /path/to/your/.env \
    ghcr.io/sooperset/mcp-atlassian:latest \
    --transport streamable-http --stateless --port 9000 -vv

{
  "mcpServers": {
    "mcp-atlassian-service": {
      "url": "http://localhost:9000/mcp",
      "headers": {
        "Authorization": "Bearer <USER_OAUTH_ACCESS_TOKEN>"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-atlassian-service": {
      "url": "http://localhost:9000/mcp",
      "headers": {
        "Authorization": "Token <USER_PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}

• jira_get_issue: Get details of a specific issue
• jira_search: Search issues using JQL
• jira_create_issue: Create a new issue (supports additional_fields as a dictionary or JSON string)
• jira_update_issue: Update an existing issue
• jira_transition_issue: Transition an issue to a new status
• jira_add_comment: Add a comment to an issue
• jira_get_customfield_options: Get available options for custom fields
• jira_get_customfield_contexts: Get contexts for custom fields
• jira_get_customfield_context_options: Get options for custom fields within specific contexts

• confluence_search: Search Confluence content using CQL
• confluence_get_page: Get content of a specific page (supports version history)
• get_page_versions: Get version information for a page
• confluence_create_page: Create a new page
• confluence_update_page: Update an existing page
• confluence_move_page: Move a page to a new location
• confluence_get_user_details: Gets information about a confluence user

*Tool only available on Jira Cloud

The server provides two ways to control tool access:

1. Tool Filtering: Use --enabled-tools flag or ENABLED_TOOLS environment variable to specify which tools should be available:

   # 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" ...

2. Read/Write Control: Tools are categorized as read or write operations. When READ_ONLY_MODE is enabled, only read operations are available regardless of ENABLED_TOOLS setting.

• Authentication Failures:
  • For Cloud: Check your API tokens (not your account password)
  • For Server/Data Center: Verify your personal access token is valid and not expired
  • For older Confluence servers: Some older versions require basic authentication with CONFLUENCE_USERNAME and CONFLUENCE_API_TOKEN (where token is your password)
• SSL Certificate Issues: If using Server/Data Center and encounter SSL errors, set CONFLUENCE_SSL_VERIFY=false or JIRA_SSL_VERIFY=false
• Permission Errors: Ensure your Atlassian account has sufficient permissions to access the spaces/projects
• Custom Headers Issues: See the "Debugging Custom Headers" section below to analyze and resolve issues with custom headers

To verify custom headers are being applied correctly:

1. Enable Debug Logging: Set MCP_VERY_VERBOSE=true to see detailed request logs

   # In your .env file or environment
   MCP_VERY_VERBOSE=true
   MCP_LOGGING_STDOUT=true

2. Check Header Parsing: Custom headers appear in logs with masked values for security:

   DEBUG Custom headers applied: {'X-Forwarded-User': '***', 'X-ALB-Token': '***'}
   

3. Verify Service-Specific Headers: Check logs to confirm the right headers are being used:

   DEBUG Jira request headers: service-specific headers applied
   DEBUG Confluence request headers: service-specific headers applied
   

4. Test Header Format: Ensure your header string format is correct:

   # Correct format
   JIRA_CUSTOM_HEADERS=X-Custom=value1,X-Other=value2
   CONFLUENCE_CUSTOM_HEADERS=X-Custom=value1,X-Other=value2
   
   # Incorrect formats (will be ignored)
   JIRA_CUSTOM_HEADERS="X-Custom=value1,X-Other=value2"  # Extra quotes
   JIRA_CUSTOM_HEADERS=X-Custom: value1,X-Other: value2  # Colon instead of equals
   JIRA_CUSTOM_HEADERS=X-Custom = value1               # Spaces around equals

Security Note: Header values containing sensitive information (tokens, passwords) are automatically masked in logs to prevent accidental exposure.

# Using MCP Inspector for testing
npx @modelcontextprotocol/inspector uvx mcp-atlassian ...

# For local development version
npx @modelcontextprotocol/inspector uv --directory /path/to/your/mcp-atlassian run mcp-atlassian ...

# View logs
# macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
# Windows
type %APPDATA%\Claude\logs\mcp*.log | more

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

This fork follows a structured development process using OpenSpec for change management.

1. Read Development Guidelines: Check openspec/AGENTS.md for comprehensive development instructions
2. Create OpenSpec Proposal: For new features or breaking changes, create structured proposals in /openspec/changes/
3. Use Development Tools: Leverage scripts in /scripts/ for testing and validation
4. Real API Testing: Use the comprehensive test suite including live API testing capabilities

We welcome contributions to MCP Atlassian! If you'd like to contribute:

1. Check out our CONTRIBUTING.md guide for detailed development setup instructions.
2. For this fork: Review openspec/AGENTS.md for the structured development workflow
3. Make changes and submit a pull request.

We use pre-commit hooks for code quality and follow semantic versioning for releases.

This fork aims to maintain compatibility with upstream sooperset/mcp-atlassian while adding enhanced development capabilities. Major improvements may be contributed back to upstream where appropriate.

Licensed under MIT - see LICENSE file. This is not an official Atlassian product.