mcp-atlassian

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

Confluence Demo

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

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

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

B. Personal Access Token (Server/Data Center)

• Go to your profile (avatar) → Profile → Personal Access Tokens
• Click Create token, name it, set expiry
• 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.

• Go to Atlassian Developer Console
• Create an "OAuth 2.0 (3LO) integration" app
• Configure Permissions (scopes) for Jira/Confluence
• Set Callback URL (e.g., http://localhost:8080/callback)
• 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
  

• Follow prompts for Client ID, Secret, URI, and Scope
• Complete browser authorization
• 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] Include offline_access in scope for persistent auth (e.g., read:jira-work write:jira-work offline_access)

📦 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:

• Passing Variables Directly (shown in examples below)
• 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": "[e-mail]",
        "CONFLUENCE_API_TOKEN": "your_confluence_api_token",
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "[e-mail]",
        "JIRA_API_TOKEN": "your_jira_api_token"
      }
    }
  }
}

Alternative: Using Environment File

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

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.

OAuth 2.0 Configuration (Cloud Only)

This example shows how to configure mcp-atlassian in your IDE (like Cursor or Claude Desktop) when using OAuth 2.0 for Atlassian Cloud. Ensure you have completed the OAuth setup wizard first.

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

[!NOTE]

• ATLASSIAN_OAUTH_CLOUD_ID is obtained from the --oauth-setup wizard output.
• Other ATLASSIAN_OAUTH_* variables are those you configured for your OAuth app in the Atlassian Developer Console (and used as input to the setup wizard).
• JIRA_URL and CONFLUENCE_URL for your Cloud instances are still required.

Proxy Configuration

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.

Single Service Configurations

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": "[e-mail]",
        "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": "[e-mail]",
        "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"
      }
    }
  }
}

👥 HTTP Transport Configuration

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

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)

Basic HTTP Transport Setup

• 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
  

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

Multi-User Authentication Setup

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

• 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
  

• 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
  

• 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 <USER_OAUTH_ACCESS_TOKEN>"
      }
    }
  }
}

Server/Data Center (PAT) Example:

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

• 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.
• 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

Tools

Key Tools

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

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

View All Tools

Operation	Jira Tools	Confluence Tools
Read	jira_search	confluence_search
	jira_get_issue	confluence_get_page
	jira_get_project_issues	confluence_get_page_children
	jira_get_worklog	confluence_get_comments
	jira_get_transitions	confluence_get_labels
	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_batch_get_changelogs*
	jira_get_user_profile
	jira_download_attachments
	jira_get_project_versions
Write	jira_create_issue	confluence_create_page
	jira_update_issue	confluence_update_page
	jira_delete_issue	confluence_delete_page
	jira_batch_create_issues	confluence_add_label
	jira_add_comment	confluence_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

*Tool only available on Jira Cloud

Tool Filtering and Access Control

The server provides two ways to control tool access:

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

• 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:

• Check out our CONTRIBUTING.md guide for detailed development setup instructions.
• 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.