📌Overview

Purpose: The MCP Atlassian framework serves to facilitate seamless integration between Atlassian products, namely Confluence and Jira, enhancing productivity and collaboration.

Overview: The Model Context Protocol (MCP) server for Atlassian products supports both cloud and server/data center deployments. It allows for efficient interaction with Confluence and Jira by providing a set of tools to manage project documentation and issue tracking within a unified platform.

Key Features:

Multi-Deployment Support: Fully supports both Cloud and Server/Data Center versions of Confluence (7.9+) and Jira (8.14+), ensuring flexibility in product usage.
Comprehensive Toolset: Offers various API tools for operations in Confluence and Jira, including searching, creating, updating, and deleting pages/issues, enhancing operational efficiencies.
Customizable Configuration: Users can easily configure the MCP server with command line arguments or environment variables, making it adaptable to different user needs and environments.

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"

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

Generate the necessary authentication tokens for Confluence & Jira.

For Cloud

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

For Server/Data Center

Go to your profile (avatar) → Profile → Personal Access Tokens
Click Create token, name it, set expiry
Copy the token immediately

2. Installation

The primary way to use MCP Atlassian is through IDE integration.

Option 1: Using uvx (Recommended)

Install uv first:

macOS/Linux:

# Using the official installer
curl -LsSf https://astral.sh/uv/install.sh | sh

# Alternatively, on macOS you can use Homebrew
brew install uv

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

With uv installed, you can use uvx mcp-atlassian directly in your IDE configuration without installing the package separately.

Option 2: Using pip

pip install mcp-atlassian

Option 3: Using Smithery

npx -y @smithery/cli install mcp-atlassian --client claude

Option 4: Using Docker

Pull the Docker image:

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

Alternatively, build it locally:

git clone https://github.com/sooperset/mcp-atlassian.git
cd mcp-atlassian
docker build -t mcp/atlassian .

3. Key Configuration Options

Use these optional environment variables in your IDE configuration:

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

You can configure just Confluence, just Jira, or both services by including only the relevant variables.

See the .env.example file in the repository for all options.

IDE Integration

MCP Atlassian is designed for AI assistants via IDE integration.

To configure in Claude Desktop:

Method 1 (Recommended): Click hamburger menu (☰) > Settings > Developer > "Edit Config" button

Method 2: Edit config 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 → Features → MCP Servers → + Add new global MCP server

Using uvx (Recommended)

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_api_token",
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_api_token"
      }
    }
  }
}

Server/Data Center Configuration

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "CONFLUENCE_URL": "https://confluence.your-company.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your_token",
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_PERSONAL_TOKEN": "your_token"
      }
    }
  }
}

Single Service Configurations

Confluence only:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_api_token"
      }
    }
  }
}

Jira only:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_api_token"
      }
    }
  }
}

Alternative: Using CLI Arguments

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": [
        "mcp-atlassian",
        "--confluence-url=https://your-company.atlassian.net/wiki",
        "--confluence-username=your.email@company.com",
        "--confluence-token=your_api_token",
        "--jira-url=https://your-company.atlassian.net",
        "--jira-username=your.email@company.com",
        "--jira-token=your_api_token"
      ]
    }
  }
}

Using pip

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "mcp-atlassian",
      "env": {
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_api_token",
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_api_token"
      }
    }
  }
}

Using Docker

Method 1: Using Environment Variables

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/sooperset/mcp-atlassian:latest",
        "--confluence-url=https://your-company.atlassian.net/wiki",
        "--confluence-username=your.email@company.com",
        "--confluence-token=your_api_token",
        "--jira-url=https://your-company.atlassian.net",
        "--jira-username=your.email@company.com",
        "--jira-token=your_api_token"
      ]
    }
  }
}

Method 2: Using an Environment File

Create a .env file based on the .env.example template and populate it, then use:

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

SSE Transport Configuration

To use Server-Sent Events (SSE) instead of stdio:

Start the server:

uvx mcp-atlassian --transport sse --port 9000 \
  --confluence-url https://your-company.atlassian.net/wiki \
  --confluence-username your.email@company.com \
  --confluence-token your_api_token \
  --jira-url https://your-company.atlassian.net \
  --jira-username your.email@company.com \
  --jira-token your_api_token

Configure in your IDE as:

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

Resources and Tools

Resources

confluence://{space_key}: Access Confluence spaces
jira://{project_key}: Access Jira projects

The MCP server filters resources to only show Confluence spaces and Jira projects that the user is actively interacting with, based on their contributions and assignments.

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

View All Tools

Confluence Tools	Jira Tools
`confluence_search`	`jira_get_issue`
`confluence_get_page`	`jira_search`
`confluence_get_page_children`	`jira_get_project_issues`
`confluence_get_page_ancestors`	`jira_get_epic_issues`
`confluence_get_comments`	`jira_create_issue`
`confluence_create_page`	`jira_batch_create_issues`
`confluence_update_page`	`jira_update_issue`
`confluence_delete_page`	`jira_delete_issue`
	`jira_get_transitions`
	`jira_transition_issue`
	`jira_add_comment`
	`jira_add_worklog`
	`jira_get_worklog`
	`jira_download_attachments`
	`jira_link_to_epic`
	`jira_get_agile_boards`
	`jira_get_board_issues`
	`jira_get_sprints_from_board`
	`jira_get_sprint_issues`
	`jira_update_sprint`
	`jira_create_issue_link`
	`jira_remove_issue_link`

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: These may require basic authentication with CONFLUENCE_USERNAME and CONFLUENCE_API_TOKEN (token may be your password)
SSL Certificate Issues: If using Server/Data Center and encountering SSL errors, set CONFLUENCE_SSL_VERIFY=false or JIRA_SSL_VERIFY=false
Permission Errors: Ensure your Atlassian account has sufficient permissions to access 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 in the repository for best practices

Contributing

We welcome contributions! To contribute:

See CONTRIBUTING.md in the repository

Set up your development environment:

uv sync --frozen --all-extras --dev
pre-commit install

Make changes and submit a pull request

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

License

Licensed under MIT. This is not an official Atlassian product.