MCP Atlassian

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

Compatibility

Quick Start Guide

1. Authentication Setup

MCP Atlassian supports three authentication methods:

A. API Token Authentication (Cloud)

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

1. Create an OAuth 2.0 integration in Atlassian:

   • Go to https://developer.atlassian.com/console/myapps/
   • Click "Create" and select "OAuth 2.0 integration"
   • Follow the wizard to create your app
   • Configure permissions for both Jira and Confluence as needed
   • Add a callback URL (e.g., http://localhost:8080/callback)

2. Run the OAuth authorization helper:

   uvx mcp-atlassian@latest --oauth-setup
   

   This will guide you through the setup process by prompting for the required values (Client ID, Client Secret, etc.).

   Alternatively, you can clone the repository and run the script directly:

   # Clone the repository if you haven't already
   git clone https://github.com/sooperset/mcp-atlassian.git
   cd mcp-atlassian
   
   # Run the OAuth authorization script
   python scripts/oauth_authorize.py \
     --client-id YOUR_CLIENT_ID \
     --client-secret YOUR_CLIENT_SECRET \
     --redirect-uri "http://localhost:8080/callback" \
     --scope "read:jira-work write:jira-work read:confluence-space.summary write:confluence-content"
   

3. Follow the browser prompt to authorize the application

4. After successful authorization, add the displayed environment variables to your .env file

2. Installation

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

IDE Integration

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

[!TIP] For Claude Desktop: Locate and edit the configuration file directly:

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

For Cursor: Open Settings → MCP → + Add new global MCP server

Configuration Methods

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)

[!NOTE] Common environment variables include:

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

See the .env.example file for all available options.

Configuration Examples

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",
        "-e", "CONFLUENCE_URL",
        "-e", "JIRA_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": {
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "JIRA_URL": "https://your-company.atlassian.net",
        "ATLASSIAN_OAUTH_CLIENT_ID": "your_client_id",
        "ATLASSIAN_OAUTH_CLIENT_SECRET": "your_client_secret",
        "ATLASSIAN_OAUTH_REDIRECT_URI": "http://localhost:8080/callback",
        "ATLASSIAN_OAUTH_SCOPE": "read:jira-work write:jira-work read:confluence-space.summary write:confluence-content",
        "ATLASSIAN_OAUTH_CLOUD_ID": "your_cloud_id"
      }
    }
  }
}

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

SSE Transport Configuration

Tools

Key Tools

Confluence Tools

• confluence_search: Search Confluence content using CQL
• confluence_get_page: Get content of a specific page
• confluence_create_page: Create a new page
• confluence_update_page: Update an existing page

Jira Tools

• jira_get_issue: Get details of a specific issue
• jira_search: Search issues using JQL
• jira_create_issue: Create a new issue
• 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

Tool Filtering and Access Control

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.

Troubleshooting & Debugging

Common Issues

• 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

Debugging Tools

# 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

Security

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

Contributing

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. Make changes and submit a pull request.

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

License

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