Model Context Protocol: Atlassian Integration Module

This repository details the implementation of the Model Context Protocol (MCP) server designed to interface with Atlassian's core platforms: Confluence and Jira.

[ [ [ []

This specialized MCP handler enables AI agents to interact programmatically with organizational data residing in Confluence wikis and Jira ticketing systems, supporting both perpetual (Server/DC) and SaaS (Cloud) installations.

Illustrative Use Cases

Instruct your AI agent to execute tasks such as:

• Automated Ticket Modifications - "Synchronize Jira status based on the latest discussion summary."
• Intelligent Knowledge Retrieval - "Locate the Q3 OKR document within Confluence and synthesize the primary objectives."
• Expedited Defect Triage - "Present all high-priority defects filed against 'ALPHA' project in the preceding seven calendar days."
• Structured Document Generation - "Draft the technical specification artifact for the new authentication module."

Feature Showcase

[Link to Feature Demo Asset: 35303504-14c6-4ae4-913b-7c25ea511c3e]

Confluence Specific Demonstration

[Link to Confluence Demo Asset: 7fe9c488-ad0c-4876-9b54-120b666bb785]

Deployment Compatibility Matrix

Platform	Deployment Model	Operational Status
Confluence	Cloud (SaaS)	✅ Fully Operational
Confluence	Server/Data Center	✅ Supported (v6.0+)
Jira	Cloud (SaaS)	✅ Fully Operational
Jira	Server/Data Center	✅ Supported (v8.14+)

Initial Setup Protocol

🔐 Phase 1: Credential Provisioning

Authentication to Atlassian services can be established via three distinct mechanisms:

Method A: API Token Credentialing (Cloud Preferred)

1. Navigate to your Atlassian security settings: https://id.atlassian.com/manage-profile/security/api-tokens
2. Generate a new token, assign a descriptive label, and immediately capture the generated secret.

Method B: Personal Access Token (Server/Data Center)

1. Access your user profile section (via avatar) → Select Profile → Navigate to Personal Access Tokens.
2. Initiate token creation, assign a name, and specify an expiration boundary.
3. Securely record the resulting token.

Method C: OAuth 2.0 Authorization (Cloud Only) - Advanced Flow

[!NOTE] OAuth 2.0 offers superior security characteristics but involves a more involved initial configuration compared to Method A (API Token).

1. Register a new application in the Atlassian Developer Console.
2. Configure the necessary security scopes for Jira/Confluence access.
3. Define the application's redirect URI (e.g., http://localhost:8080/callback).

4. Execute the configuration utility within the provided container: bash docker run --rm -i \ -p 8080:8080 \ -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \ ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v

5. Input the necessary data prompted by the wizard: Client ID, Secret, URI, and required Scope.

6. Authorize the application via the browser prompt.
7. Persist credentials in your runtime configuration (.env or IDE settings):
8. ATLASSIAN_OAUTH_CLOUD_ID (Retrieved from wizard completion)
9. ATLASSIAN_OAUTH_CLIENT_ID
10. ATLASSIAN_OAUTH_CLIENT_SECRET
11. ATLASSIAN_OAUTH_REDIRECT_URI
12. ATLASSIAN_OAUTH_SCOPE

[!IMPORTANT] For sustained OAuth operation, ensure offline_access is included in the scope definition (e.g., read:jira-work write:jira-work offline_access). This permits transparent token refresh.

Alternative: Direct Token Injection (BYOT)

If your infrastructure already manages the lifecycle of OAuth 2.0 access tokens (e.g., via a centralized identity broker), you can supply an existing token directly. This bypasses the server's internal token management, including automatic refresh capabilities. **Prerequisites:** - A valid Atlassian OAuth 2.0 Access Token carrying the required functional scopes. - Knowledge of the corresponding `ATLASSIAN_OAUTH_CLOUD_ID`. **Configuration Variables:** - Set `ATLASSIAN_OAUTH_CLOUD_ID`: Your designated Cloud ID. (CLI flag: `--oauth-cloud-id`) - Set `ATLASSIAN_OAUTH_ACCESS_TOKEN`: The pre-obtained access token. (CLI flag: `--oauth-access-token`) **Critical Caveats for BYOT:** - **Refresh Responsibility**: The MCP server will *not* manage token expiration or renewal. This duty remains entirely with the external system supplying the token. - **Unnecessary Variables**: Client configuration variables (`CLIENT_ID`, `CLIENT_SECRET`, etc.) are ignored. - **Wizard Inapplicability**: The `--oauth-setup` utility should not be invoked when using BYOT. - **Volume Omission**: The Docker volume mount for persistent token storage is not required. - **Scope Validation**: The supplied token must already possess the necessary permissions for all intended Jira/Confluence API calls. This method is advantageous for tightly integrated systems where credential oversight is externalized.

[!TIP] For developing multi-tenant applications requiring per-user connections, consult the section on .

📦 Phase 2: Deployment and Containerization

Deployment is streamlined via a pre-compiled Docker image, which is the preferred execution environment for IDE integrations.

Ensure Docker is installed, then pull the latest image:

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

Integration into Development Environments

The Atlassian MCP server is architected for seamless integration with AI-enabled development platforms.

[!TIP] Claude Desktop Users: Modify the configuration file located at: - Windows: %APPDATA%\Claude\claude_desktop_config.json - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Linux: ~/.config/Claude/claude_desktop_config.json

Cursor IDE Users: Access Settings → Model Context Protocol → + Add New Global MCP Server

⚙️ Configuration Methodologies

Integration relies on two primary configuration paradigms:

1. Direct Environment Variable Injection (Illustrated in usage examples below).
2. Utilizing an External Environment File via the --env-file argument.

[!NOTE] Available runtime directives include:

• CONFLUENCE_SPACES_FILTER: Define space keys to limit scope (e.g., "DEV,TEAM,DOC").
• JIRA_PROJECTS_FILTER: Specify project keys for filtering (e.g., "PROJ,DEV,SUPPORT").
• READ_ONLY_MODE: Set to "true" to restrict all modification actions.
• MCP_VERBOSE: Enable extended logging output ("true").
• MCP_LOGGING_STDOUT: Reroute logs from stderr to stdout ("true").
• ENABLED_TOOLS: A comma-separated enumeration of tools to expose (e.g., "confluence_search,jira_get_issue").

Refer to the .env.example file for a complete parameter registry.

📝 Configuration Templates (JSON Format)

Method 1: Direct Variable Passing

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

Alternative: Environment File Usage

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

For self-hosted environments, substitute API tokens with Personal Access Tokens (PATs) and handle SSL verification as needed: { "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 the `*_SSL_VERIFY` flags to "false" judiciously, typically only when employing internal, self-signed certificate authorities.

OAuth 2.0 Configuration Examples (Cloud Instances)

These JSON snippets demonstrate configuration for IDE integration using OAuth 2.0 credentials against Atlassian Cloud. **Standard Flow (Server Manages Tokens via 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] > - The volume mount (`-v .../.mcp-atlassian:/home/app/.mcp-atlassian`) is vital for persistent storage and automatic token refreshing. > - `JIRA_URL` and `CONFLUENCE_URL` must point to your Cloud instances. **Pre-existing Token Injection (BYOT):** { "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 BYOT, client-specific OAuth credentials are ignored. > - You are responsible for refreshing the injected access token before it becomes invalid.

Proxy Integration Setup

To route API requests through an intermediary proxy server (HTTP, HTTPS, or SOCKS), utilize standard proxy environment variables. Service-specific overrides (`JIRA_HTTPS_PROXY`, etc.) take precedence over global ones (`HTTPS_PROXY`). { "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" } } } } Proxy credential details are masked in log outputs for security.

Configuring Custom HTTP Headers

Inject custom HTTP headers into API requests using comma-separated `KEY=VALUE` environment variables for both Jira and Confluence services. This is useful for corporate gateways or internal service routing. { "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", "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-Jira-Client=mcp-integration" } } } } **Security Protocol**: Sensitive header values are automatically obfuscated within service logs.

Multi-Tenant OAuth Support (HTTP Transport)

This setup enables a single server instance to handle API calls for multiple distinct Atlassian tenants using per-request user credentials. 1. **Enable Minimal Server Mode (Streamable HTTP):** bash docker run -e ATLASSIAN_OAUTH_ENABLE=true -p 9000:9000 \ ghcr.io/sooperset/mcp-atlassian:latest \ --transport streamable-http --port 9000 2. **Client-Side Request Authentication:** Users must supply their token and Cloud ID via request headers: - `Authorization: Bearer ` - `X-Atlassian-Cloud-Id: ` **Client Integration Example (Python using streamablehttp_client):** 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(): 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, _): async with ClientSession(read_stream, write_stream) as session: await session.initialize() result = await session.call_tool( "jira_get_issue", {"issue_key": "PROJ-123"} ) print(result) asyncio.run(main()) **Configuration Notes:** - The Cloud ID header allows routing to the correct tenant; otherwise, the server's globally configured `ATLASSIAN_OAUTH_CLOUD_ID` is used as a fallback. - This architecture isolates user data pathways.

👥 Persistent HTTP Service Mode

Transitioning from stdio (standard I/O) to a network service offers persistence. Use either Server-Sent Events (sse endpoint /sse) or the robust streamable-http transport (/mcp endpoint).

Authentication for HTTP Service: - Single Tenant: Rely on server-level environment variables. - Multi-Tenant: Inject user-specific credentials (Authorization header) per request.

Standard HTTP Service Startup

1. Initiate the service: bash # 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 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. IDE Configuration (Example using Streamable-HTTP): { "mcpServers": { "mcp-atlassian-service": { "url": "http://localhost:9000/mcp" } } }

Multi-User Authentication over HTTP Transport

This flow requires initial OAuth setup followed by starting the HTTP service, where user tokens are passed in HTTP headers. 1. **Prerequisite:** Run the OAuth setup wizard (see Phase 1, Method C) to configure the server's base OAuth application credentials. 2. **Start HTTP Server:** bash 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. **IDE Configuration (Cloud OAuth Example):** { "mcpServers": { "mcp-atlassian-service": { "url": "http://localhost:9000/mcp", "headers": { "Authorization": "Bearer " } } } } 4. **Required `.env` Variables (Server Auth Fallback):** bash 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=...offline_access ATLASSIAN_OAUTH_CLOUD_ID=your_cloud_id_from_setup_wizard > [!NOTE] > - For Server/DC multi-tenant use, substitute the `Authorization` header with `Token `. > - The server uses user tokens if present, otherwise falling back to the credentials defined in the environment variables.

Exposed Functionality (Tools Registry)

Core Toolsets

Jira Operations

• jira_get_issue: Retrieves granular data for a specified issue identifier.
• jira_search: Executes parameterized JQL queries for issue retrieval.
• jira_create_issue: Provisions a new ticket within a project.
• jira_update_issue: Modifies attributes of an existing issue record.
• jira_transition_issue: Advances an issue through its defined workflow status.
• jira_add_comment: Appends contextual notes to an issue thread.

Confluence Operations

• confluence_search: Performs content lookup using Confluence Query Language (CQL).
• confluence_get_page: Fetches the rendered content body of a specific page.
• confluence_create_page: Generates new content entities within a designated space.
• confluence_update_page: Overwrites or appends content to an existing document.

Complete Tool Index

| Intent | Jira Tools | Confluence Tools | |---|---|---| | **Query** | `jira_search`, `jira_get_issue`, `jira_get_all_projects`, `jira_get_project_issues`, `jira_get_worklog`, `jira_get_transitions`, `jira_search_fields`, `jira_get_agile_boards`, `jira_get_board_issues`, `jira_get_sprints_from_board`, `jira_get_sprint_issues`, `jira_get_issue_link_types`, `jira_get_user_profile`, `jira_download_attachments`, `jira_get_project_versions` | `confluence_search`, `confluence_get_page`, `confluence_get_page_children`, `confluence_get_comments`, `confluence_get_labels`, `confluence_search_user` | | **Modification** | `jira_create_issue`, `jira_update_issue`, `jira_delete_issue`, `jira_batch_create_issues`, `jira_add_comment`, `jira_transition_issue`, `jira_add_worklog`, `jira_link_to_epic`, `jira_create_sprint`, `jira_update_sprint`, `jira_create_issue_link`, `jira_remove_issue_link`, `jira_create_version`, `jira_batch_create_versions` | `confluence_create_page`, `confluence_update_page`, `confluence_delete_page`, `confluence_add_label`, `confluence_add_comment` |

Access Restriction and Scoping

Tool availability is managed via two mechanisms:

1. Tool Whitelisting: Utilize the --enabled-tools command argument or the ENABLED_TOOLS environment variable to whitelist specific functions (e.g., ENABLED_TOOLS="confluence_search,jira_get_issue").

2. Operational Mode: Enabling READ_ONLY_MODE will neutralize all write-enabled tools, regardless of the whitelist configuration.

Diagnostics and Debugging

Common Operational Hurdles

• Authentication Failure: Reconfirm usage of API/PAT secrets (not account passwords) for Cloud/Server respectively. Older Confluence instances might require legacy Basic Auth using the password in place of the token.
• TLS/SSL Errors: For Server/DC, explicitly disable certificate validation by setting *_SSL_VERIFY=false.
• Authorization Denied: Verify the authenticated user identity possesses the necessary ACL rights for the targeted Jira projects or Confluence spaces.
• Header Misconfiguration: Refer to the guide below for diagnosing issues related to custom request headers.

Debugging Custom Header Transmission

1. Activate Verbose Logging: Set MCP_VERY_VERBOSE=true and MCP_LOGGING_STDOUT=true.
2. Log Inspection: Examine detailed output for the application of headers. Sensitive components will be masked:

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

1. Format Validation: Headers must strictly adhere to KEY=VALUE pairs, separated by commas, without extraneous quotes or spaces around the equals sign. Example: bash CONFLUENCE_CUSTOM_HEADERS=X-Header-One=ValueA,X-Header-Two=ValueB

External Diagnostic Utilities

To test connectivity and tool invocation outside the IDE:

bash

Using the MCP Inspector CLI tool

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

For local source development testing

npx @modelcontextprotocol/inspector uv --directory /path/to/your/mcp-atlassian run mcp-atlassian ...

Security Posture

• Treat all generated API keys and tokens as confidential secrets.
• Always secure .env files.
• Consult the SECURITY.md file for comprehensive security guidelines.

Development and Contribution

We encourage community enhancements. Review the CONTRIBUTING.md for development environment setup.

Intellectual Property

Distributed under the MIT License. This integration module is an independent project and not officially endorsed by Atlassian Pty Ltd.

[WIKIPEDIA CONTEXT] Business management instruments encompass the applications, control mechanisms, computational resolutions, and systematic approaches utilized by enterprises to adapt to dynamic marketplaces, maintain competitive advantage, and elevate operational effectiveness. These tools span departmental needs, including strategic forecasting, process orchestration, record maintenance, human resource management, and critical decision support.

The evolution of these tools has been rapid, driven by technological leaps, making selection a strategic exercise rather than a reactive one. Successful organizations prioritize adapting their processes to fit robust tools, rather than forcing tool implementation onto existing, potentially incompatible workflows.

Key areas of focus frequently mentioned in business literature include:

• Strategic Planning Frameworks
• Customer Relationship Management (CRM)
• Performance Measurement (e.g., Balanced Scorecard)
• Operational Efficiency (e.g., Supply Chain Management)

Modern business software (applications) ranges from foundational MIS to complex cloud-native ERP suites, emphasizing effective implementation and appropriate tool selection as the primary drivers of realized value.