mcp-atlassian

# MCP Atlassian    [](https://github.com/sooperset/mcp-atlassian/actions/workflows/tests.yml)  Model Context Protocol (MCP) server for Atlassian products (Confluence and Jira). This integration supports both Confluence & Jira Cloud and Server/Data Center deployments. ## Example Usage 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" ### Feature Demo https://github.com/user-attachments/assets/35303504-14c6-4ae4-913b-7c25ea511c3e <details> <summary>Confluence Demo</summary> https://github.com/user-attachments/assets/7fe9c488-ad0c-4876-9b54-120b666bb785 </details> ### Compatibility | 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+) | ## Quick Start Guide ### 🔐 1. Authentication Setup MCP Atlassian supports three authentication methods: #### A. API Token Authentication (Cloud) - **Recommended** 1. Go to https://id.atlassian.com/manage-profile/security/api-tokens 2. Click **Create API token**, name it 3. Copy the token immediately #### B. Personal Access Token (Server/Data Center) 1. Go to your profile (avatar) → **Profile** → **Personal Access Tokens** 2. Click **Create token**, name it, set expiry 3. Copy the token immediately #### C. OAuth 2.0 Authentication (Cloud) - **Advanced** > [!NOTE] > OAuth 2.0 is more complex to set up but provides enhanced security features. For most users, API Token authentication (Method A) is simpler and sufficient. 1. Go to [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/) 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: ```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 ``` 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` > [!IMPORTANT] > For the standard OAuth flow described above, include `offline_access` in your scope (e.g., `read:jira-work write:jira-work offline_access`). This allows the server to refresh the access token automatically. <details> <summary>Alternative: Using a Pre-existing OAuth Access Token (BYOT)</summary> 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_