https://github.com/user-attachments/assets/7fe9c488-ad0c-4876-9b54-120b666bb785

If you are running mcp-atlassian part of a larger system that manages Atlassian OAuth 2.0 access tokens externally (e.g., through a central identity provider or another application), you can provide an access token directly to this MCP server. This method bypasses the interactive setup wizard and the server's internal token management (including refresh capabilities).

Requirements:

• A valid Atlassian OAuth 2.0 Access Token with the necessary scopes for the intended operations.
• The corresponding ATLASSIAN_OAUTH_CLOUD_ID for your Atlassian instance.

Configuration: To use this method, set the following environment variables (or use the corresponding command-line flags when starting the server):

• ATLASSIAN_OAUTH_CLOUD_ID: Your Atlassian Cloud ID. (CLI: --oauth-cloud-id)
• ATLASSIAN_OAUTH_ACCESS_TOKEN: Your pre-existing OAuth 2.0 access token. (CLI: --oauth-access-token)

Important Considerations for BYOT:

• Token Lifecycle Management: When using BYOT, the MCP server does not handle token refresh. The responsibility for obtaining, refreshing (before expiry), and revoking the access token lies entirely with you or the external system providing the token.
• Unused Variables: The standard OAuth client variables (ATLASSIAN_OAUTH_CLIENT_ID, ATLASSIAN_OAUTH_CLIENT_SECRET, ATLASSIAN_OAUTH_REDIRECT_URI, ATLASSIAN_OAUTH_SCOPE) are not used and can be omitted when configuring for BYOT.
• No Setup Wizard: The --oauth-setup wizard is not applicable and should not be used for this approach.
• No Token Cache Volume: The Docker volume mount for token storage (e.g., -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian") is also not necessary if you are exclusively using the BYOT method, as no tokens are stored or managed by this server.
• Scope: The provided access token must already have the necessary permissions (scopes) for the Jira/Confluence operations you intend to perform.

This option is useful in scenarios where OAuth credential management is centralized or handled by other infrastructure components.

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

For Server/Data Center deployments, use direct variable passing:

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

> [!NOTE] > Set CONFLUENCE_SSL_VERIFY and JIRA_SSL_VERIFY to "false" only if you have self-signed certificates.

These examples show how to configure mcp-atlassian in your IDE (like Cursor or Claude Desktop) when using OAuth 2.0 for Atlassian Cloud.

Example for Standard OAuth 2.0 Flow (using Setup Wizard):

This configuration is for when you use the server's built-in OAuth client and have completed the OAuth setup wizard.

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v", "/.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"
      }
    }
  }
}

> [!NOTE] > - For the Standard Flow: > - ATLASSIAN_OAUTH_CLOUD_ID is obtained from the --oauth-setup wizard output or is known for your instance. > - Other ATLASSIAN_OAUTH_* client variables are from your OAuth app in the Atlassian Developer Console. > - JIRA_URL and CONFLUENCE_URL for your Cloud instances are always required. > - The volume mount (-v .../.mcp-atlassian:/home/app/.mcp-atlassian) is crucial for persisting the OAuth tokens obtained by the wizard, enabling automatic refresh.

Example for Pre-existing Access Token (BYOT - Bring Your Own Token):

This configuration is for when you are providing your own externally managed OAuth 2.0 access token.

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

> [!NOTE] > - For the BYOT Method: > - You primarily need JIRA_URL, CONFLUENCE_URL, ATLASSIAN_OAUTH_CLOUD_ID, and ATLASSIAN_OAUTH_ACCESS_TOKEN. > - Standard OAuth client variables (ATLASSIAN_OAUTH_CLIENT_ID, CLIENT_SECRET, REDIRECT_URI, SCOPE) are not used. > - Token lifecycle (e.g., refreshing the token before it expires and restarting mcp-atlassian) is your responsibility, as the server will not refresh BYOT tokens.

MCP Atlassian supports routing API requests through standard HTTP/HTTPS/SOCKS proxies. Configure using environment variables:

• Supports standard HTTP_PROXY, HTTPS_PROXY, NO_PROXY, SOCKS_PROXY.
• Service-specific overrides are available (e.g., JIRA_HTTPS_PROXY, CONFLUENCE_NO_PROXY).
• Service-specific variables override global ones for that service.

Add the relevant proxy variables to the args (using -e) and env sections of your MCP configuration:

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

Credentials in proxy URLs are masked in logs. If you set NO_PROXY, it will be respected for requests to matching hosts.

MCP Atlassian supports adding custom HTTP headers to all API requests. This feature is particularly useful in corporate environments where additional headers are required for security, authentication, or routing purposes.

Custom headers are configured using environment variables with comma-separated key=value pairs:

{
  "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": "your.email@company.com",
        "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": "your.email@company.com",
        "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"
      }
    }
  }
}

Security Considerations:

• Custom header values are masked in debug logs to protect sensitive information
• Ensure custom headers don't conflict with standard HTTP or Atlassian API headers
• Avoid including sensitive authentication tokens in custom headers if already using basic auth or OAuth
• Headers are sent with every API request - verify they don't interfere with API functionality

MCP Atlassian supports multi-cloud OAuth scenarios where each user connects to their own Atlassian cloud instance. This is useful for multi-tenant applications, chatbots, or services where users provide their own OAuth tokens.

Minimal OAuth Configuration:

1. Enable minimal OAuth mode (no client credentials required):

   docker run -e ATLASSIAN_OAUTH_ENABLE=true -p 9000:9000 \
     ghcr.io/sooperset/mcp-atlassian:latest \
     --transport streamable-http --port 9000
   

2. Users provide authentication via HTTP headers:

   • Authorization: Bearer
   • X-Atlassian-Cloud-Id:

Example Integration (Python):

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())

Configuration Notes:

• Each request can use a different cloud instance via the X-Atlassian-Cloud-Id header
• User tokens are isolated per request - no cross-tenant data leakage
• Falls back to global ATLASSIAN_OAUTH_CLOUD_ID if header not provided
• Compatible with standard OAuth 2.0 bearer token authentication

For Confluence Cloud only:

{
  "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": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_api_token"
      }
    }
  }
}

For Confluence Server/DC, use:

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

For Jira Cloud only:

{
  "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": "your.email@company.com",
        "JIRA_API_TOKEN": "your_api_token"
      }
    }
  }
}

For Jira Server/DC, use:

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

1. Start the server with your chosen transport:

   # 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
   

2. Configure your IDE (single-user example):

   SSE Transport Example:

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

   Streamable-HTTP Transport Example:

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

Here's a complete example of setting up multi-user authentication with streamable-HTTP transport:

1. First, run the OAuth setup wizard to configure the server's OAuth credentials:

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

2. Start the server with 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
   

3. Configure your IDE's MCP settings:

Choose the appropriate Authorization method for your Atlassian deployment:

• Cloud (OAuth 2.0): Use this if your organization is on Atlassian Cloud and you have an OAuth access token for each user.
• Server/Data Center (PAT): Use this if you are on Atlassian Server or Data Center and each user has a Personal Access Token (PAT).

Cloud (OAuth 2.0) Example:

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

Server/Data Center (PAT) Example:

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

4. Required environment variables in .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
   

> [!NOTE] > - The server should have its own fallback authentication configured (e.g., via environment variables for API token, PAT, or its own OAuth setup using --oauth-setup). This is used if a request doesn't include user-specific authentication. > - OAuth: Each user needs their own OAuth access token from your Atlassian OAuth app. > - PAT: Each user provides their own Personal Access Token. > - Multi-Cloud: For OAuth users, optionally include X-Atlassian-Cloud-Id header to specify which Atlassian cloud instance to use > - The server will use the user's token for API calls when provided, falling back to server auth if not > - User tokens should have appropriate scopes for their needed operations