# Authentication
Source: https://personal-1d37018d.mintlify.app/docs/authentication

Configure authentication for MCP Atlassian - API tokens, PATs, and OAuth 2.0

# Authentication

MCP Atlassian supports three authentication methods depending on your Atlassian deployment type.

## API Token (Cloud) - Recommended

The simplest method for Atlassian Cloud users.

<Steps>
  <Step title="Create API Token">
    Go to [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
  </Step>

  <Step title="Generate Token">
    Click **Create API token**, give it a name
  </Step>

  <Step title="Copy Token">
    Copy the token immediately - you won't see it again
  </Step>
</Steps>

**Environment variables:**

```bash theme={null}
JIRA_URL=https://your-company.atlassian.net
JIRA_USERNAME=your.email@company.com
JIRA_API_TOKEN=your_api_token

CONFLUENCE_URL=https://your-company.atlassian.net/wiki
CONFLUENCE_USERNAME=your.email@company.com
CONFLUENCE_API_TOKEN=your_api_token
```

## Personal Access Token (Server/Data Center)

For Server or Data Center deployments.

<Steps>
  <Step title="Access Profile">
    Go to your profile (avatar) → **Profile** → **Personal Access Tokens**
  </Step>

  <Step title="Create Token">
    Click **Create token**, name it, set expiry
  </Step>

  <Step title="Copy Token">
    Copy the token immediately
  </Step>
</Steps>

**Environment variables:**

```bash theme={null}
JIRA_URL=https://jira.your-company.com
JIRA_PERSONAL_TOKEN=your_personal_access_token

CONFLUENCE_URL=https://confluence.your-company.com
CONFLUENCE_PERSONAL_TOKEN=your_personal_access_token
```

<Note>
  For self-signed certificates, set `JIRA_SSL_VERIFY=false` and/or `CONFLUENCE_SSL_VERIFY=false`.
</Note>

## OAuth 2.0 (Cloud) - Advanced

OAuth 2.0 provides enhanced security features but requires more setup. For most users, API Token authentication is simpler and sufficient.

### Setup Steps

<Steps>
  <Step title="Create OAuth App">
    Go to [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/) and create an "OAuth 2.0 (3LO) integration" app
  </Step>

  <Step title="Configure Permissions">
    Add scopes for Jira/Confluence as needed
  </Step>

  <Step title="Set Callback URL">
    Set to `http://localhost:8080/callback`
  </Step>

  <Step title="Run Setup Wizard">
    ```bash theme={null}
    # Using uvx
    uvx mcp-atlassian --oauth-setup -v

    # Or using Docker
    docker run --rm -i \
      -p 8080:8080 \
      -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \
      ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v
    ```
  </Step>

  <Step title="Complete Authorization">
    Follow prompts for Client ID, Secret, URI, and Scope, then complete browser authorization
  </Step>
</Steps>

**Environment variables (after setup):**

```bash theme={null}
JIRA_URL=https://your-company.atlassian.net
CONFLUENCE_URL=https://your-company.atlassian.net/wiki
ATLASSIAN_OAUTH_CLOUD_ID=your_cloud_id_from_wizard
ATLASSIAN_OAUTH_CLIENT_ID=your_oauth_client_id
ATLASSIAN_OAUTH_CLIENT_SECRET=your_oauth_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
```

<Warning>
  Include `offline_access` in your scope to allow automatic token refresh.
</Warning>

### Bring Your Own Token (BYOT)

If you manage OAuth tokens externally (e.g., through a central identity provider):

```bash theme={null}
ATLASSIAN_OAUTH_CLOUD_ID=your_cloud_id
ATLASSIAN_OAUTH_ACCESS_TOKEN=your_pre_existing_access_token
```

<Warning>
  Token refresh is your responsibility - the server does not handle it for BYOT.
</Warning>

### Multi-Cloud OAuth

For multi-tenant applications where users provide their own OAuth tokens:

1. Enable minimal OAuth mode:
   ```bash theme={null}
   # Using uvx
   ATLASSIAN_OAUTH_ENABLE=true uvx mcp-atlassian --transport streamable-http --port 9000

   # Or using Docker
   docker run -e ATLASSIAN_OAUTH_ENABLE=true -p 9000:9000 \
     ghcr.io/sooperset/mcp-atlassian:latest \
     --transport streamable-http --port 9000
   ```

2. Users provide authentication via HTTP headers:
   * `Authorization: Bearer <user_oauth_token>`
   * `X-Atlassian-Cloud-Id: <user_cloud_id>`

See [HTTP Transport](/http-transport) for more details on multi-user authentication.


# Configuration
Source: https://personal-1d37018d.mintlify.app/docs/configuration

IDE integration, environment variables, and advanced configuration options

# Configuration

This guide covers IDE integration, environment variables, and advanced configuration options.

## IDE Integration

### Configuration File Locations

| IDE                      | Location                                                          |
| ------------------------ | ----------------------------------------------------------------- |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json`                     |
| Claude Desktop (macOS)   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Desktop (Linux)   | `~/.config/Claude/claude_desktop_config.json`                     |
| Cursor                   | Settings → MCP → + Add new global MCP server                      |

### Basic Configuration (uvx)

```json theme={null}
{
  "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"
      }
    }
  }
}
```

### Docker with Environment File

```json theme={null}
{
  "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

```json theme={null}
{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_PERSONAL_TOKEN": "your_pat",
        "JIRA_SSL_VERIFY": "false",
        "CONFLUENCE_URL": "https://confluence.your-company.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your_pat",
        "CONFLUENCE_SSL_VERIFY": "false"
      }
    }
  }
}
```

### Single Service Configuration

<Tabs>
  <Tab title="Confluence Only">
    ```json theme={null}
    {
      "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"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Jira Only">
    ```json theme={null}
    {
      "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"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Environment Variables

### Connection Settings

| Variable                    | Description                                  |
| --------------------------- | -------------------------------------------- |
| `JIRA_URL`                  | Jira instance URL                            |
| `JIRA_USERNAME`             | Jira username (email for Cloud)              |
| `JIRA_API_TOKEN`            | Jira API token (Cloud)                       |
| `JIRA_PERSONAL_TOKEN`       | Jira Personal Access Token (Server/DC)       |
| `JIRA_SSL_VERIFY`           | SSL verification (`true`/`false`)            |
| `CONFLUENCE_URL`            | Confluence instance URL                      |
| `CONFLUENCE_USERNAME`       | Confluence username (email for Cloud)        |
| `CONFLUENCE_API_TOKEN`      | Confluence API token (Cloud)                 |
| `CONFLUENCE_PERSONAL_TOKEN` | Confluence Personal Access Token (Server/DC) |
| `CONFLUENCE_SSL_VERIFY`     | SSL verification (`true`/`false`)            |

### Filtering Options

| Variable                   | Description                         | Example                            |
| -------------------------- | ----------------------------------- | ---------------------------------- |
| `JIRA_PROJECTS_FILTER`     | Limit to specific Jira projects     | `PROJ,DEV,SUPPORT`                 |
| `CONFLUENCE_SPACES_FILTER` | Limit to specific Confluence spaces | `DEV,TEAM,DOC`                     |
| `ENABLED_TOOLS`            | Enable only specific tools          | `confluence_search,jira_get_issue` |

### Server Options

| Variable             | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| `TRANSPORT`          | Transport type (`stdio`, `sse`, `streamable-http`)         |
| `STATELESS`          | Enable stateless mode for streamable-http (`true`/`false`) |
| `PORT`               | Port for HTTP transports (default: `8000`)                 |
| `HOST`               | Host for HTTP transports (default: `0.0.0.0`)              |
| `READ_ONLY_MODE`     | Disable write operations (`true`/`false`)                  |
| `MCP_VERBOSE`        | Enable verbose logging (`true`/`false`)                    |
| `MCP_VERY_VERBOSE`   | Enable debug logging (`true`/`false`)                      |
| `MCP_LOGGING_STDOUT` | Log to stdout instead of stderr (`true`/`false`)           |

See [.env.example](https://github.com/sooperset/mcp-atlassian/blob/main/.env.example) for all available options.

## Proxy Configuration

MCP Atlassian supports routing API requests through HTTP/HTTPS/SOCKS proxies.

| Variable                 | Description                     |
| ------------------------ | ------------------------------- |
| `HTTP_PROXY`             | HTTP proxy URL                  |
| `HTTPS_PROXY`            | HTTPS proxy URL                 |
| `SOCKS_PROXY`            | SOCKS proxy URL                 |
| `NO_PROXY`               | Hosts to bypass proxy           |
| `JIRA_HTTPS_PROXY`       | Jira-specific HTTPS proxy       |
| `CONFLUENCE_HTTPS_PROXY` | Confluence-specific HTTPS proxy |

Service-specific variables override global ones.

## Custom HTTP Headers

Add custom HTTP headers to all API requests. Useful in corporate environments.

| Variable                    | Description                            |
| --------------------------- | -------------------------------------- |
| `JIRA_CUSTOM_HEADERS`       | Custom headers for Jira requests       |
| `CONFLUENCE_CUSTOM_HEADERS` | Custom headers for Confluence requests |

**Format:** Comma-separated `key=value` pairs.

```bash theme={null}
JIRA_CUSTOM_HEADERS=X-Forwarded-User=service-account,X-Custom-Auth=token
CONFLUENCE_CUSTOM_HEADERS=X-Service=mcp-integration,X-ALB-Token=secret
```

<Note>
  Header values are masked in debug logs for security.
</Note>

## Tool Filtering

Control which tools are available:

```bash theme={null}
# Enable specific tools
ENABLED_TOOLS="confluence_search,jira_get_issue,jira_search"

# Read-only mode (disables all write operations)
READ_ONLY_MODE=true
```

Command-line alternative:

```bash theme={null}
uvx mcp-atlassian --enabled-tools "confluence_search,jira_get_issue"
```


# HTTP Transport
Source: https://personal-1d37018d.mintlify.app/docs/http-transport

Run MCP Atlassian as an HTTP service for multi-user scenarios

# HTTP Transport

Instead of using `stdio`, you can run the server as a persistent HTTP service. This enables multi-user scenarios and remote deployment.

## Transport Types

| Transport         | Endpoint | Use Case                               |
| ----------------- | -------- | -------------------------------------- |
| `sse`             | `/sse`   | Server-Sent Events, good for streaming |
| `streamable-http` | `/mcp`   | HTTP-based, good for multi-user        |

## Stateless Mode

For Kubernetes deployments or environments where session state should be ephemeral, use the `--stateless` flag with streamable-http transport:

```bash theme={null}
# Using uvx
uvx mcp-atlassian --transport streamable-http --stateless --port 9000 -vv

# Or using Docker
docker run --rm -p 9000:9000 \
  --env-file /path/to/your/.env \
  ghcr.io/sooperset/mcp-atlassian:latest \
  --transport streamable-http --stateless --port 9000 -vv

# Or via environment variable
STATELESS=true uvx mcp-atlassian --transport streamable-http --port 9000
```

<Note>
  The `--stateless` flag is only supported with `streamable-http` transport. Using it with `stdio` or `sse` will result in an error.
</Note>

## Basic Setup

<Tabs>
  <Tab title="SSE Transport">
    ```bash theme={null}
    # Using uvx
    uvx mcp-atlassian --transport sse --port 9000 -vv

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

    **IDE Configuration:**

    ```json theme={null}
    {
      "mcpServers": {
        "mcp-atlassian-http": {
          "url": "http://localhost:9000/sse"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Streamable-HTTP">
    ```bash theme={null}
    # Using uvx
    uvx mcp-atlassian --transport streamable-http --port 9000 -vv

    # Or using Docker
    docker run --rm -p 9000:9000 \
      --env-file /path/to/your/.env \
      ghcr.io/sooperset/mcp-atlassian:latest \
      --transport streamable-http --port 9000 -vv
    ```

    **IDE Configuration:**

    ```json theme={null}
    {
      "mcpServers": {
        "mcp-atlassian-service": {
          "url": "http://localhost:9000/mcp"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Multi-User Authentication

Both transport types support per-request authentication where each user provides their own credentials.

### Authentication Methods

<Tabs>
  <Tab title="Cloud (OAuth)">
    ```json theme={null}
    {
      "mcpServers": {
        "mcp-atlassian-service": {
          "url": "http://localhost:9000/mcp",
          "headers": {
            "Authorization": "Bearer <USER_OAUTH_ACCESS_TOKEN>"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Server/DC (PAT)">
    ```json theme={null}
    {
      "mcpServers": {
        "mcp-atlassian-service": {
          "url": "http://localhost:9000/mcp",
          "headers": {
            "Authorization": "Token <USER_PERSONAL_ACCESS_TOKEN>"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Server Setup for Multi-User

<Steps>
  <Step title="Run OAuth Setup (if using OAuth)">
    ```bash theme={null}
    # Using uvx
    uvx mcp-atlassian --oauth-setup -v

    # Or using Docker
    docker run --rm -i \
      -p 8080:8080 \
      -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \
      ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v
    ```
  </Step>

  <Step title="Start HTTP Server">
    ```bash theme={null}
    # Using uvx (with env vars set)
    uvx mcp-atlassian --transport streamable-http --port 9000 -vv

    # Or using Docker
    docker run --rm -p 9000:9000 \
      --env-file /path/to/your/.env \
      ghcr.io/sooperset/mcp-atlassian:latest \
      --transport streamable-http --port 9000 -vv
    ```
  </Step>

  <Step title="Configure Environment">
    ```bash theme={null}
    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
    ```
  </Step>
</Steps>

### Multi-Cloud Support

For multi-tenant applications where each user connects to their own Atlassian cloud instance:

1. Enable minimal OAuth mode:
   ```bash theme={null}
   # Using uvx
   ATLASSIAN_OAUTH_ENABLE=true uvx mcp-atlassian --transport streamable-http --port 9000

   # Or using Docker
   docker run -e ATLASSIAN_OAUTH_ENABLE=true -p 9000:9000 \
     ghcr.io/sooperset/mcp-atlassian:latest \
     --transport streamable-http --port 9000
   ```

2. Users provide authentication via HTTP headers:
   * `Authorization: Bearer <user_oauth_token>`
   * `X-Atlassian-Cloud-Id: <user_cloud_id>`

### Python Example

```python theme={null}
import asyncio
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

user_token = "user-specific-oauth-token"
user_cloud_id = "user-specific-cloud-id"

async def main():
    async with streamablehttp_client(
        "http://localhost:9000/mcp",
        headers={
            "Authorization": f"Bearer {user_token}",
            "X-Atlassian-Cloud-Id": user_cloud_id
        }
    ) as (read_stream, write_stream, _):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            result = await session.call_tool(
                "jira_get_issue",
                {"issue_key": "PROJ-123"}
            )
            print(result)

asyncio.run(main())
```

<Note>
  * The server uses fallback authentication when requests don't include user-specific credentials
  * User tokens are isolated per request - no cross-tenant data leakage
  * Falls back to global `ATLASSIAN_OAUTH_CLOUD_ID` if header not provided
</Note>


# MCP Atlassian
Source: https://personal-1d37018d.mintlify.app/docs/index

Model Context Protocol server for Jira and Confluence

# MCP Atlassian

Model Context Protocol (MCP) server for Atlassian products (Confluence and Jira). Supports both Cloud and Server/Data Center deployments.

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/installation">
    Get started in 5 minutes with uvx
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Set up API tokens, PATs, or OAuth 2.0
  </Card>

  <Card title="Tools Reference" icon="wrench" href="/tools-reference">
    Browse all available Jira and Confluence tools
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration">
    IDE setup and environment variables
  </Card>
</CardGroup>

## Example Usage

Ask your AI assistant to:

* **"Find issues assigned to me in PROJ project"**
* **"Search Confluence for onboarding docs"**
* **"Create a bug ticket for the login issue"**
* **"Update the status of PROJ-123 to Done"**

## Compatibility

| Product    | Deployment         | Support            |
| ---------- | ------------------ | ------------------ |
| Confluence | Cloud              | Fully supported    |
| Confluence | Server/Data Center | Supported (v6.0+)  |
| Jira       | Cloud              | Fully supported    |
| Jira       | Server/Data Center | Supported (v8.14+) |

<Note>
  Python 3.14 is not yet supported due to upstream pydantic-core/PyO3 limitations. Use Python 3.10-3.13.
</Note>


# Installation
Source: https://personal-1d37018d.mintlify.app/docs/installation

Install MCP Atlassian using uvx, Docker, pip, or from source

# Installation

MCP Atlassian can be installed using several methods. Choose the one that best fits your workflow.

## uvx (Recommended)

The simplest way to run MCP Atlassian without permanent installation using [uvx](https://docs.astral.sh/uv/guides/tools/):

```bash theme={null}
# Run directly (downloads on first use, cached for subsequent runs)
uvx mcp-atlassian --help

# Run with specific Python version (required for Python 3.14+)
uvx --python=3.12 mcp-atlassian --help
```

### IDE Configuration with uvx

<Tabs>
  <Tab title="Claude Desktop">
    Edit your config file:

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

    ```json theme={null}
    {
      "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_confluence_api_token",
            "JIRA_URL": "https://your-company.atlassian.net",
            "JIRA_USERNAME": "your.email@company.com",
            "JIRA_API_TOKEN": "your_jira_api_token"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    Open **Settings** → **MCP** → **+ Add new global MCP server**, then use the same JSON configuration.
  </Tab>
</Tabs>

<Note>
  Python 3.14 is not yet supported due to upstream pydantic-core/PyO3 limitations.
  Use `["--python=3.12", "mcp-atlassian"]` as args if needed.
</Note>

## Docker

Docker provides an isolated environment and is recommended for production deployments or when you need specific version control.

```bash theme={null}
# Pull the latest image
docker pull ghcr.io/sooperset/mcp-atlassian:latest

# Run with environment variables
docker run --rm -i \
  -e JIRA_URL=https://your-company.atlassian.net \
  -e JIRA_USERNAME=your.email@company.com \
  -e JIRA_API_TOKEN=your_api_token \
  ghcr.io/sooperset/mcp-atlassian:latest
```

### IDE Configuration with Docker

```json theme={null}
{
  "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": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_confluence_api_token",
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_jira_api_token"
      }
    }
  }
}
```

See [Configuration](/configuration) for more Docker options including environment files.

## pip

Install directly with pip for development or when you need the package in your Python environment:

```bash theme={null}
pip install mcp-atlassian

# Run the server
mcp-atlassian --help
```

## uv

If you're using [uv](https://docs.astral.sh/uv/) for package management:

```bash theme={null}
# Add to your project
uv add mcp-atlassian

# Run
uv run mcp-atlassian --help
```

## From Source

For development or contributing:

```bash theme={null}
git clone https://github.com/sooperset/mcp-atlassian.git
cd mcp-atlassian
uv sync --frozen --all-extras --dev
uv run mcp-atlassian --help
```

See [CONTRIBUTING.md](https://github.com/sooperset/mcp-atlassian/blob/main/CONTRIBUTING.md) for development setup details.


# Tools Reference
Source: https://personal-1d37018d.mintlify.app/docs/tools-reference

All available MCP Atlassian tools for Jira and Confluence

# Tools Reference

MCP Atlassian provides tools for interacting with Jira and Confluence.

## Key Tools

<CardGroup>
  <Card title="Jira Tools" icon="list-check">
    | Tool                    | Description                     |
    | ----------------------- | ------------------------------- |
    | `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 issue to new status  |
    | `jira_add_comment`      | Add a comment to an issue       |
  </Card>

  <Card title="Confluence Tools" icon="book">
    | Tool                     | Description                    |
    | ------------------------ | ------------------------------ |
    | `confluence_search`      | Search 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        |
  </Card>
</CardGroup>

## Complete Tool List

| Operation | Jira Tools                    | Confluence Tools               |
| --------- | ----------------------------- | ------------------------------ |
| **Read**  | `jira_search`                 | `confluence_search`            |
|           | `jira_get_issue`              | `confluence_get_page`          |
|           | `jira_get_all_projects`       | `confluence_get_page_children` |
|           | `jira_get_project_issues`     | `confluence_get_comments`      |
|           | `jira_get_worklog`            | `confluence_get_labels`        |
|           | `jira_get_transitions`        | `confluence_search_user`       |
|           | `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`      |                                |
|           | `jira_create_version`         |                                |
|           | `jira_batch_create_versions`  |                                |

<Note>
  \* `jira_batch_get_changelogs` is only available on Jira Cloud
</Note>

## Tool Access Control

### Enable Specific Tools

Use `ENABLED_TOOLS` environment variable or `--enabled-tools` flag:

```bash theme={null}
# Environment variable
ENABLED_TOOLS="confluence_search,jira_get_issue,jira_search"

# Command line
uvx mcp-atlassian --enabled-tools "confluence_search,jira_get_issue,jira_search"
```

### Read-Only Mode

Disable all write operations:

```bash theme={null}
READ_ONLY_MODE=true
```

When enabled, only read operations are available regardless of `ENABLED_TOOLS` setting.


# Troubleshooting
Source: https://personal-1d37018d.mintlify.app/docs/troubleshooting

Common issues and debugging tips for MCP Atlassian

# Troubleshooting

## Common Issues

<AccordionGroup>
  <Accordion title="Authentication Failures (Cloud)">
    * Ensure you're using API tokens, not your account password
    * Verify the token hasn't expired
    * Check that `JIRA_USERNAME` / `CONFLUENCE_USERNAME` is your email address
  </Accordion>

  <Accordion title="Authentication Failures (Server/Data Center)">
    * Verify your Personal Access Token is valid and not expired
    * For older Confluence servers, try basic auth with `CONFLUENCE_USERNAME` and `CONFLUENCE_API_TOKEN` (where token is your password)
  </Accordion>

  <Accordion title="SSL Certificate Issues">
    For Server/Data Center with self-signed certificates:

    ```bash theme={null}
    JIRA_SSL_VERIFY=false
    CONFLUENCE_SSL_VERIFY=false
    ```
  </Accordion>

  <Accordion title="Permission Errors">
    Ensure your Atlassian account has sufficient permissions to access the spaces/projects you're targeting.
  </Accordion>

  <Accordion title="Python Version Issues">
    Python 3.14 is not yet supported due to upstream pydantic-core/PyO3 limitations.

    **Workaround with uvx:**

    ```bash theme={null}
    uvx --python=3.12 mcp-atlassian
    ```

    **In IDE configuration:**

    ```json theme={null}
    {
      "args": ["--python=3.12", "mcp-atlassian"]
    }
    ```
  </Accordion>
</AccordionGroup>

## Debugging

### Enable Verbose Logging

```bash theme={null}
# Standard verbose
MCP_VERBOSE=true

# Debug level (includes request details)
MCP_VERY_VERBOSE=true

# Log to stdout instead of stderr
MCP_LOGGING_STDOUT=true
```

### View Logs

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
    ```
  </Tab>

  <Tab title="Windows">
    ```cmd theme={null}
    type %APPDATA%\Claude\logs\mcp*.log | more
    ```
  </Tab>
</Tabs>

### MCP Inspector

Test your configuration interactively:

```bash theme={null}
# With uvx
npx @modelcontextprotocol/inspector uvx mcp-atlassian

# With local development version
npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-atlassian run mcp-atlassian
```

## Debugging Custom Headers

### Verify Headers Are Applied

1. Enable debug logging:
   ```bash theme={null}
   MCP_VERY_VERBOSE=true
   MCP_LOGGING_STDOUT=true
   ```

2. Check logs for header confirmation:
   ```
   DEBUG Custom headers applied: {'X-Forwarded-User': '***', 'X-ALB-Token': '***'}
   ```

### Correct Header Format

```bash theme={null}
# Correct
JIRA_CUSTOM_HEADERS=X-Custom=value1,X-Other=value2

# Incorrect (extra quotes)
JIRA_CUSTOM_HEADERS="X-Custom=value1,X-Other=value2"

# Incorrect (colon instead of equals)
JIRA_CUSTOM_HEADERS=X-Custom: value1,X-Other: value2

# Incorrect (spaces around equals)
JIRA_CUSTOM_HEADERS=X-Custom = value1
```

<Note>
  Header values containing sensitive information are automatically masked in logs.
</Note>

## Getting Help

* Check [GitHub Issues](https://github.com/sooperset/mcp-atlassian/issues) for known problems
* Review [SECURITY.md](https://github.com/sooperset/mcp-atlassian/blob/main/SECURITY.md) for security-related concerns
* Open a new issue with debug logs if the problem persists