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

mcp-atlassian-jira-demo.mp4

Confluence Demo

confluence-1k.mp4

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)

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

Go to Atlassian Developer Console
Create an "OAuth 2.0 integration"
Configure necessary Permissions (scopes) for Jira/Confluence
Set Callback URL (e.g., http://localhost:8080/callback for setup wizard)

Run the OAuth setup wizard:

uvx mcp-atlassian@latest --oauth-setup -v

Follow the prompts to enter your Client ID, Client Secret, Redirect URI and Scope.
Complete the authorization in the opened browser window
Add the ATLASSIAN_OAUTH_CLOUD_ID (obtained from the wizard output) along with your OAuth app's CLIENT_ID, SECRET, REDIRECT_URI, and SCOPE to your .env file or IDE's MCP server configuration. See the OAuth 2.0 Configuration Example in the "Configuration Examples" section for IDE integration.

Important

Include offline_access in your ATLASSIAN_OAUTH_SCOPE for persistent authentication (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": "[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"
      }
    }
  }
}

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": "uvx",
      "args": [
        "mcp-atlassian",
      ],
      "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": "[email protected]",
        "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": "[email protected]",
        "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"
      }
    }
  }
}

SSE Transport Configuration

Using SSE Instead of stdio

Start the server manually in a terminal:

docker run --rm -p 9000:9000 \
  --env-file /path/to/your/.env \
  ghcr.io/sooperset/mcp-atlassian:latest \
  --transport sse --port 9000 -vv

Configure your IDE to connect to the running server via its URL:

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

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_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`
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`
	`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.

Name		Name	Last commit message	Last commit date
Latest commit History 251 Commits
.devcontainer		.devcontainer
.github		.github
scripts		scripts
src/mcp_atlassian		src/mcp_atlassian
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
pyproject.toml		pyproject.toml
smithery.yaml		smithery.yaml
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

MCP Atlassian

Example Usage

Feature Demo

Compatibility

Quick Start Guide

1. Authentication Setup

A. API Token Authentication (Cloud)

B. Personal Access Token (Server/Data Center)

C. OAuth 2.0 Authentication (Cloud only)

2. Installation

IDE Integration

Configuration Methods

Configuration Examples

SSE Transport Configuration

Tools

Key Tools

Jira Tools

Confluence Tools

Tool Filtering and Access Control

Troubleshooting & Debugging

Common Issues

Debugging Tools

Security

Contributing

License

About

Releases 38

Packages

Contributors 39

Languages

License

sooperset/mcp-atlassian

Folders and files

Latest commit

History

Repository files navigation

MCP Atlassian

Example Usage

Feature Demo

Compatibility

Quick Start Guide

1. Authentication Setup

A. API Token Authentication (Cloud)

B. Personal Access Token (Server/Data Center)

C. OAuth 2.0 Authentication (Cloud only)

2. Installation

IDE Integration

Configuration Methods

Configuration Examples

SSE Transport Configuration

Tools

Key Tools

Jira Tools

Confluence Tools

Tool Filtering and Access Control

Troubleshooting & Debugging

Common Issues

Debugging Tools

Security

Contributing

License

About

Topics

Resources

License

Security policy

Stars

Watchers

Forks

Releases 38

Packages 0

Contributors 39

Languages

Packages