### Get Create Fields example parameters

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-search-fields

Example JSON parameters for the Get Create Fields tool, specifying a project key and issue type ID.

```json
{
  "project_key": "PROJ",
  "issue_type_id": "10002"
}
```

--------------------------------

### Get Agile Boards - Example JSON

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-agile

Example request for the Get Agile Boards tool. Supports fuzzy search by board name and can be combined with project_key to narrow results.

```json
{"board_name": "Sprint Board", "project_key": "PROJ", "board_type": "scrum"}
```

--------------------------------

### Batch Get Changelogs example

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-comments-worklogs

Example input for the Batch Get Changelogs tool. It accepts a list of issue keys or IDs.

```json
{"issue_keys": ["PROJ-1", "PROJ-2", "PROJ-3"]}
```

--------------------------------

### SSE transport setup with IDE configuration

Source: https://mcp-atlassian.soomiles.com/docs/http-transport

Start the server with SSE transport and configure an IDE client to connect to the /sse endpoint. The server runs on port 9000 with verbose logging.

```bash
# 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

```

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

```

--------------------------------

### Streamable-HTTP transport setup with IDE configuration

Source: https://mcp-atlassian.soomiles.com/docs/http-transport

Start the server with streamable-http transport and configure an IDE client to connect to the /mcp endpoint. The server runs on port 9000 with verbose logging.

```bash
# 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

```

```json
{
  "mcpServers": {
    "mcp-atlassian-service": {
      "url": "http://localhost:9000/mcp"
    }
  }
}

```

--------------------------------

### Get Content Attachments Example

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-attachments

Example payload for the Get Content Attachments tool, filtering by media_type 'application/octet-stream' to list binary attachments.

```json
{"content_id": "12345678", "media_type": "application/octet-stream"}
```

--------------------------------

### Get Space Permissions Example

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-permissions

Lists all permission assignments for a Confluence space. Requires a numeric space_id, with optional limit and cursor parameters. This example requests up to 50 permission entries for a specified space.

```json
{"space_id": "98304", "limit": 50}
```

--------------------------------

### Run OAuth Setup Wizard

Source: https://mcp-atlassian.soomiles.com/docs/authentication

Runs the OAuth setup wizard to configure OAuth 2.0 (3LO) for Jira/Confluence. Use either uvx or Docker; the Docker command mounts the local configuration directory and exposes port 8080 for the callback.

```bash
# 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
```

--------------------------------

### Run OAuth Setup (uvx and Docker)

Source: https://mcp-atlassian.soomiles.com/docs/http-transport

Run the OAuth setup wizard to obtain OAuth credentials. Two equivalent commands are shown: one using uvx and one using Docker. The Docker command mounts the local .mcp-atlassian directory and exposes port 8080.

```bash
# Using uvx
uvx mcp-atlassian --oauth-setup -v

```

```bash
# 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

```

--------------------------------

### Start HTTP Server (uvx and Docker)

Source: https://mcp-atlassian.soomiles.com/docs/http-transport

Start the MCP HTTP server with the streamable-http transport on port 9000. Two equivalent commands are shown: one using uvx with environment variables set, and one using Docker with an env file.

```bash
# Using uvx (with env vars set)
uvx mcp-atlassian --transport streamable-http --port 9000 -vv

```

```bash
# 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

```

--------------------------------

### Jira key validation patterns for Data Center

Source: https://mcp-atlassian.soomiles.com/docs/configuration

Example environment variables for a Data Center instance whose project keys may start with a digit (e.g., 4ME-123). Widen the default patterns if your instance allows keys the defaults reject.

```bash
# Data Center instance whose project keys may start with a digit (e.g. 4ME-123)
JIRA_ISSUE_KEY_PATTERN=^[A-Z0-9][A-Z0-9_]*-\d+(?:-\d+)*$
JIRA_PROJECT_KEY_PATTERN=^[A-Z0-9][A-Z0-9_]*$
```

--------------------------------

### Get Sprint Issues - Example JSON

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-agile

Example request for the Get Sprint Issues tool. Get the sprint ID from jira_get_sprints_from_board first.

```json
{"sprint_id": "42", "fields": "summary,status,assignee,story_points"}
```

--------------------------------

### Get Project Issue Types example JSON

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-search-fields

Example payload for the Get Project Issue Types tool. Retrieves issue types for project PROJ.

```json
{"project_key": "PROJ"}
```

--------------------------------

### Install MCP Atlassian with pip

Source: https://mcp-atlassian.soomiles.com/docs/installation

Install MCP Atlassian with pip. Use the [wpad] extra when PAC/WPAD proxy routing is enabled, then run the server with mcp-atlassian --help.

```bash
pip install mcp-atlassian

# Include this extra when PAC/WPAD proxy routing is enabled
pip install "mcp-atlassian[wpad]"

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

--------------------------------

### Get Page Views Example

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-comments

Example JSON payload for fetching view statistics for a Confluence page. Includes page_id and period.

```json
{"page_id": "12345678", "period": "lastMonth"}
```

--------------------------------

### Get Field Options example JSON

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-search-fields

Example payload for the Get Field Options tool. Retrieves options for custom field customfield_10001 containing 'high', limited to 5 results, returning only values.

```json
{"field_id": "customfield_10001", "contains": "high", "return_limit": 5, "values_only": true}
```

--------------------------------

### Download Attachments - Example JSON Input

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-attachments

Example input for the Download Attachments tool. The issue_key parameter is required and should be a Jira issue key like 'PROJ-123'.

```json
{"issue_key": "PROJ-123"}
```

--------------------------------

### Install MCP Atlassian from source

Source: https://mcp-atlassian.soomiles.com/docs/installation

Clone the repository and set up a development environment. Uses uv sync with --frozen --all-extras --dev, then runs the server.

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

--------------------------------

### Docker run quick start

Source: https://mcp-atlassian.soomiles.com/docs/advanced/docker-production

Runs the MCP Atlassian container with required environment variables for Jira and Confluence.

```bash
docker run -i --rm \
  -e JIRA_URL=https://your-company.atlassian.net \
  -e JIRA_USERNAME=your.email@example.com \
  -e JIRA_API_TOKEN=your_api_token \
  -e CONFLUENCE_URL=https://your-company.atlassian.net/wiki \
  -e CONFLUENCE_USERNAME=your.email@example.com \
  -e CONFLUENCE_API_TOKEN=your_api_token \
  ghcr.io/sooperset/mcp-atlassian:latest
```

--------------------------------

### Get Issue Example - JSON Request

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-issues

Example JSON payload for the Get Issue tool. Uses issue_key 'PROJ-123', requests specific fields, limits comments to 5, and includes remote links and transitions.

```json
{"issue_key": "PROJ-123", "fields": "summary,status,assignee", "comment_limit": 5, "include": "remote_links,transitions"}
```

--------------------------------

### Get Issue SLA example payload

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-forms-metrics

Example JSON payload for the Get Issue SLA tool, specifying the issue key and metrics to calculate. The metrics parameter accepts a comma-separated list of SLA metrics, defaulting to configured metrics or 'cycle_time,time_in_status'.

```json
{
  "issue_key": "SD-456",
  "metrics": "cycle_time,time_in_status"
}
```

--------------------------------

### Add Comment example

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-comments-worklogs

Example input for the Add Comment tool. The body supports Markdown formatting and mentions on Jira Cloud.

```json
{"issue_key": "PROJ-123", "body": "## Investigation\n\nFound the root cause in module X."}
```

--------------------------------

### Add Issues to Sprint - Example JSON

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-agile

Example request for the Add Issues to Sprint tool. Get sprint IDs from jira_get_sprints_from_board. Issue keys are validated server-side — invalid keys will cause an error.

```json
{"sprint_id": "42", "issue_keys": "PROJ-1,PROJ-2,PROJ-3"}
```

--------------------------------

### Transition Issue Example

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-issues

Example JSON payload for transitioning an issue to a new status. Use jira_get_transitions first to see available transitions. The comment is optional and may be rejected for internal-only projects.

```json
{"issue_key": "PROJ-123", "transition_name": "Done", "comment": "Closing as completed"}
```

--------------------------------

### CQL Query Example

Source: https://mcp-atlassian.soomiles.com/docs/guides/cql-guide

Pass a CQL string directly to search. This example finds pages in the DEV space with 'Meeting Notes' in the title.

```cql
type=page AND space=DEV AND title~"Meeting Notes"

```

--------------------------------

### Get All Projects

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-issues

Gets all Jira projects accessible to the current user.

```APIDOC
## Get All Projects

### Description
Get all Jira projects accessible to the current user.

### Parameters
#### Query Parameters
- `include_archived` (boolean) - Optional - Whether to include archived projects in the results
```

--------------------------------

### Get Page Version Diff request example

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-pages

Example request body for the Get Page Version Diff tool. The page_id is the numeric ID from the page URL, and from_version and to_version are the source and target version numbers. Use confluence_get_page_history to discover available version numbers.

```json
{"page_id": "12345678", "from_version": 1, "to_version": 3}
```

--------------------------------

### Install MCP Atlassian with uv

Source: https://mcp-atlassian.soomiles.com/docs/installation

Add MCP Atlassian to a uv-managed project. Use the [wpad] extra when PAC/WPAD proxy routing is enabled, then run with uv run.

```bash
# Add to your project
uv add mcp-atlassian

# Include this extra when PAC/WPAD proxy routing is enabled
uv add "mcp-atlassian[wpad]"

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

--------------------------------

### Upload Attachment Example (content_base64)

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-attachments

Example payload for the Upload Attachment tool using the 'content_base64' parameter, which requires the 'filename' parameter.

```json
{"content_id": "12345678", "content_base64": "SGVsbG8=", "filename": "hello.txt"}
```

--------------------------------

### Create Issue Example - JSON Request

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-issues

Example JSON payload for the Create Issue tool. Creates a Task in project PROJ with a Markdown description.

```json
{"project_key": "PROJ", "issue_type": "Task", "summary": "Implement new feature", "description": "## Requirements\n\n- Feature A\n- Feature B"}
```

--------------------------------

### Python client example for multi-cloud

Source: https://mcp-atlassian.soomiles.com/docs/http-transport

Python example using the MCP streamable HTTP client to call a tool with user-specific OAuth token and cloud ID headers. Requests without user-specific credentials are rejected unless ALLOW_GLOBAL_CRED_FALLBACK=true. User tokens are isolated per request, and it falls back to global ATLASSIAN_OAUTH_CLOUD_ID if the header is not provided.

```python
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())

```

--------------------------------

### Search Issues example JSON

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-search-fields

Example payload for the Search Issues tool. Uses JQL to find issues in project PROJ with status 'In Progress', ordered by updated date, limited to 20 results.

```json
{"jql": "project = PROJ AND status = 'In Progress' ORDER BY updated DESC", "limit": 20}
```

--------------------------------

### Upload Attachment Example (file_path)

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-attachments

Example payload for the Upload Attachment tool using the 'file_path' parameter. The comment field is optional and can be omitted if not needed.

```json
{"content_id": "12345678", "file_path": "/path/to/diagram.png", "comment": "Updated architecture diagram"}
```

--------------------------------

### Docker Compose basic setup

Source: https://mcp-atlassian.soomiles.com/docs/advanced/docker-production

Defines a basic Docker Compose service for MCP Atlassian with SSE transport and port mapping.

```yaml
version: "3.8"
services:
  mcp-atlassian:
    image: ghcr.io/sooperset/mcp-atlassian:latest
    env_file: .env
    ports:
      - "8000:8000"
    environment:
      - TRANSPORT=sse
      - PORT=8000
      - HOST=0.0.0.0
    restart: unless-stopped
```

--------------------------------

### Get Transitions

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-issues

Gets available status transitions for a Jira issue.

```APIDOC
## Get Transitions

### Description
Get available status transitions for a Jira issue.

### Parameters
#### Path Parameters
- `issue_key` (string) - Required - Jira issue key (e.g., 'PROJ-123', 'ACV2-642')
```

--------------------------------

### Simple Text Search Example

Source: https://mcp-atlassian.soomiles.com/docs/guides/cql-guide

Pass plain text to confluence_search, which auto-detects and uses siteSearch. This example searches for 'project documentation architecture'.

```text
project documentation architecture

```

--------------------------------

### Run MCP stdio readiness probe

Source: https://mcp-atlassian.soomiles.com/docs/compatibility

Runs the readiness probe with default settings, emitting JSON with protocol version, tool names, and installed package versions. Does not invoke any Atlassian tool.

```bash
uv run python scripts/mcp_wire_probe.py \
  --server-command uv \
  --server-arg=run \
  --server-arg=mcp-atlassian

```

--------------------------------

### Search Fields example JSON

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-search-fields

Example payload for the Search Fields tool. Searches for fields matching 'story points' with issue type Story and project key PROJ.

```json
{"keyword": "story points", "issue_type": "Story", "project_key": "PROJ"}
```

--------------------------------

### Check Content Permissions Example

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-permissions

Checks whether a user or group can perform an operation on specific content. Usage requires content_id, user_identifier, and operation parameters. This example checks read permission for a specific user on a content item.

```json
{"content_id": "12345678", "user_identifier": "5b10a2844c20165700ede21g", "operation": "read"}
```

--------------------------------

### Run readiness probe with protocol version and tool expectations

Source: https://mcp-atlassian.soomiles.com/docs/compatibility

Adds version-specific expectations to the probe, making protocol negotiation and tool discovery explicit gates. The expected protocol revision is lane-specific and should not be inferred from the installed MCP SDK major version.

```bash
uv run python scripts/mcp_wire_probe.py \
  --server-command uv \
  --server-arg=run \
  --server-arg=mcp-atlassian \
  --expect-protocol-version=2025-11-25 \
  --expect-tool-absent=jira_create_issue

```

--------------------------------

### Run Multi-Cloud OAuth Server

Source: https://mcp-atlassian.soomiles.com/docs/authentication

Starts the server in minimal OAuth mode for multi-tenant applications where users provide their own OAuth tokens. Users then authenticate via HTTP headers: Authorization: Bearer <user_oauth_token> and X-Atlassian-Cloud-Id: <user_cloud_id>.

```bash
# 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
```

--------------------------------

### Reply to Comment Example

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-comments

Example JSON payload for replying to an existing comment thread. Requires comment_id and body in Markdown format.

```json
{"comment_id": "67890", "body": "Thanks for the feedback! I've updated the section."}
```

--------------------------------

### Environment file pattern

Source: https://mcp-atlassian.soomiles.com/docs/advanced/docker-production

Example .env file for storing sensitive credentials. Never commit .env files to version control; add .env to .gitignore.

```bash
# .env
JIRA_URL=https://your-company.atlassian.net
JIRA_USERNAME=your.email@example.com
JIRA_API_TOKEN=your_api_token
CONFLUENCE_URL=https://your-company.atlassian.net/wiki
CONFLUENCE_USERNAME=your.email@example.com
CONFLUENCE_API_TOKEN=your_api_token
```

--------------------------------

### Example production SLA configuration

Source: https://mcp-atlassian.soomiles.com/docs/advanced/sla-metrics

A typical production SLA configuration. It calculates cycle time, time-in-status, and lead time, counts only business hours, and uses the US Eastern timezone.

```bash
# Calculate cycle time and time-in-status
JIRA_SLA_METRICS=cycle_time,time_in_status,lead_time

# Count only business hours
JIRA_SLA_WORKING_HOURS_ONLY=true
JIRA_SLA_WORKING_HOURS_START=09:00
JIRA_SLA_WORKING_HOURS_END=17:00
JIRA_SLA_WORKING_DAYS=1,2,3,4,5

# US Eastern timezone
JIRA_SLA_TIMEZONE=America/New_York
```

--------------------------------

### Search Content Example: CQL Query

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-search

Example JSON payload for the Search Content tool using a CQL query to find pages in the DEV space with 'Architecture' in the title. The query parameter accepts either simple text or CQL, and the limit parameter is optional (1-50).

```json
{"query": "type=page AND space=DEV AND title~'Architecture'", "limit": 10}
```

--------------------------------

### Move Page example payload

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-pages

Example payload for moving a Confluence page to a new parent. At least one of target_parent_id or target_space_key must be provided; omitting target_parent_id with a space key moves to the space root.

```json
{"page_id": "12345678", "target_parent_id": "98765432"}
```

--------------------------------

### Move Issue to Project Example

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-issues

Example JSON payload for moving an issue to another project. The issue keeps its current type and may receive a new key in the target project. Only available for Jira Cloud.

```json
{"issue_key": "PROJ-123", "target_project_key": "OTHERPROJ"}
```

--------------------------------

### Get Labels

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-comments

Gets labels for Confluence content (pages, blog posts, or attachments).

```APIDOC
## Get Labels

### Description
Gets labels for Confluence content (pages, blog posts, or attachments).

### Parameters
- **page_id** (string) - Required - Confluence content ID (page, blog post, or attachment). For pages: numeric ID from URL (e.g., '123456789'). For attachments: ID with 'att' prefix (e.g., 'att123456789'). Works with any Confluence content type that supports labels.
```

--------------------------------

### Add Comment Example

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-comments

Example JSON payload for adding a comment to a Confluence page. Requires page_id and body in Markdown format.

```json
{"page_id": "12345678", "body": "Great documentation! Consider adding examples for the API section."}
```

--------------------------------

### Update Issue Example

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-issues

Example JSON payload for the Update Issue tool, showing how to set fields, transition, comment, and log work. The fields value is a JSON string with escaped quotes. Use return_fields to reduce response size.

```json
{"issue_key": "PROJ-123", "fields": "{\"summary\": \"Updated title\", \"description\": \"New description\"}", "transition": "Done", "comment": "Completed the work", "worklog": "1h"}
```

--------------------------------

### Basic CQL Query Syntax

Source: https://mcp-atlassian.soomiles.com/docs/guides/cql-guide

Shows the basic CQL pattern: field operator value. This example queries for pages in the DEV space.

```cql
type = page AND space = "DEV"

```

--------------------------------

### Update Page Example

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-pages

Example JSON payload for updating a Confluence page. Requires page_id and title; content is optional but either content or content_file must be provided. Setting is_minor_edit to true skips notification emails.

```json
{"page_id": "12345678", "title": "Updated Title", "content": "## Updated Content\n\nNew information...", "is_minor_edit": true}
```

--------------------------------

### Copy Page example payload

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-pages

Example payload for copying a Confluence page to a new location. When destination_parent_id is omitted, the page is created at the space root. copy_attachments defaults to true and is only supported on Confluence Cloud.

```json
{"source_page_id": "12345678", "destination_space_key": "DOCS", "new_title": "Copied Runbook", "destination_parent_id": "98765432"}
```

--------------------------------

### Sprint Planning with Jira Agile Tools

Source: https://mcp-atlassian.soomiles.com/docs/guides/common-workflows

Workflow for sprint planning: get scrum boards, list active/future sprints, review sprint issues, and find backlog items for the next sprint.

```json
jira_get_agile_boards: {"project_key": "PROJ", "board_type": "scrum"}
```

```json
jira_get_sprints_from_board: {"board_id": "42", "state": "active,future"}
```

```json
jira_get_sprint_issues: {"sprint_id": "100", "fields": "summary,status,story_points,assignee"}
```

```json
jira_search: {"jql": "project = PROJ AND sprint IS EMPTY AND status = 'Open' ORDER BY priority DESC, created ASC", "limit": 30}
```

--------------------------------

### Get Project Components

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-links-versions

Retrieves all components for a specific Jira project.

```APIDOC
## Get Project Components

### Description
Get all components for a specific Jira project.

### Parameters
#### Query Parameters
- **project_key** (string) - Required - Jira project key (e.g., 'PROJ', 'ACV2')

```

--------------------------------

### Docker Compose multi-service setup

Source: https://mcp-atlassian.soomiles.com/docs/advanced/docker-production

Runs separate Jira and Confluence services with distinct environment files and toolset configurations.

```yaml
version: "3.8"
services:
  jira-mcp:
    image: ghcr.io/sooperset/mcp-atlassian:latest
    env_file: .env.jira
    ports:
      - "8001:8000"
    environment:
      - TRANSPORT=sse
      - PORT=8000
      - TOOLSETS=jira_issues,jira_fields,jira_transitions

  confluence-mcp:
    image: ghcr.io/sooperset/mcp-atlassian:latest
    env_file: .env.confluence
    ports:
      - "8002:8000"
    environment:
      - TRANSPORT=sse
      - PORT=8000
      - TOOLSETS=confluence_pages,confluence_comments
```

--------------------------------

### Get Service Desk For Project

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-service-desk

Retrieves the Jira Service Desk associated with a given project key.

```APIDOC
## Get Service Desk For Project

### Description
Get the Jira Service Desk associated with a project key.

### Parameters

- `project_key` (string) - Required - Jira project key (e.g., 'SUP')

### Response
Returns the service desk details for the specified project.
```

--------------------------------

### Configure Environment for OAuth

Source: https://mcp-atlassian.soomiles.com/docs/http-transport

Environment variables required for OAuth setup, including Jira and Confluence URLs, OAuth client credentials, redirect URI, scopes, cloud ID, and optional proxy settings. The optional ATLASSIAN_OAUTH_PROXY_ENABLE and PUBLIC_BASE_URL enable MCP OAuth proxy and DCR/discovery endpoints.

```bash
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
# Optional: enable MCP OAuth proxy + DCR/discovery endpoints
ATLASSIAN_OAUTH_PROXY_ENABLE=true
PUBLIC_BASE_URL=https://mcp.example.com/mcp-atlassian

```

--------------------------------

### OAuth Environment Variables

Source: https://mcp-atlassian.soomiles.com/docs/authentication

Environment variables required after completing the OAuth setup wizard. Include offline_access in the scope to allow automatic token refresh.

```bash
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
```

--------------------------------

### Run MCP Atlassian with uvx

Source: https://mcp-atlassian.soomiles.com/docs/installation

Run MCP Atlassian directly with uvx, downloading on first use and caching for subsequent runs. Optionally specify a Python version with --python.

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

# Run with a specific Python version if needed
uvx --python=3.12 mcp-atlassian --help
```

--------------------------------

### Enable specific tools with ENABLED_TOOLS

Source: https://mcp-atlassian.soomiles.com/docs/tools-reference

Use ENABLED_TOOLS environment variable or --enabled-tools flag to enable only specific tools by name. The example shows enabling confluence_search, jira_get_issue, and jira_search.

```bash
# 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"

```

--------------------------------

### Get Space Permissions

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-permissions

Lists all permission assignments for a Confluence space. Only available for Confluence Cloud.

```APIDOC
## Get Space Permissions

### Description
Lists all permission assignments for a Confluence space. Only available for Confluence Cloud.

### Parameters
#### Request Body
- **space_id** (string) - Required - Numeric ID of the Confluence space. This is the internal space ID, not the space key. Example: '98304'. You can find the space ID from the Confluence REST API (GET /wiki/api/v2/spaces) or from the space URL.
- **limit** (integer) - Optional - Maximum number of permission entries to return. Defaults to 25.
- **cursor** (string) - Optional - Optional pagination cursor from a previous response.

### Request Example
{"space_id": "98304", "limit": 50}

### Notes
This tool is only available for Confluence Cloud. Calling it on Server/Data Center raises `ValueError` because those deployments use different permission APIs.
```

--------------------------------

### Get Issues Development Info

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-forms-metrics

Retrieves development information for multiple Jira issues.

```APIDOC
## Get Issues Development Info

### Description
Get development information for multiple Jira issues.

### Parameters
#### Path Parameters
- **issue_keys** (string) - Required - Comma-separated list of Jira issue keys (e.g., 'PROJ-123,PROJ-456')
- **application_type** (string) - Optional - Filter by application type (case-sensitive). Examples: 'stash' (Bitbucket Server), 'bitbucket', 'GitHub', 'githube' (GitHub Enterprise Server), 'GitLab'. If omitted, types are discovered automatically.
- **data_type** (string) - Optional - Filter by data type. Examples: 'pullrequest', 'branch', 'repository'

```

--------------------------------

### Basic Configuration (uvx)

Source: https://mcp-atlassian.soomiles.com/docs/configuration

Configures the mcp-atlassian server using uvx with Jira credentials. Replace the placeholder values with your actual Jira URL, username, and API token.

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

```

--------------------------------

### Get Comments

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-comments

Gets comments for a specific Confluence page.

```APIDOC
## Get Comments

### Description
Gets comments for a specific Confluence page.

### Parameters
- **page_id** (string) - Required - Confluence page ID (numeric ID, can be parsed from URL, e.g. from 'https://example.atlassian.net/wiki/spaces/TEAM/pages/123456789/Page+Title' -> '123456789').

### Notes
Replies include `parent_comment_id` when Confluence provides the parent thread. Inline comments also include `marker_ref`, `original_selection`, and `resolution_status` when available.
```

--------------------------------

### Get Project Issues

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-issues

Gets all issues for a specific Jira project.

```APIDOC
## Get Project Issues

### Description
Get all issues for a specific Jira project.

### Parameters
#### Path Parameters
- `project_key` (string) - Required - Jira project key (e.g., 'PROJ', 'ACV2')
- `limit` (integer) - Optional - Maximum number of results (1-50)
- `start_at` (integer) - Optional - Starting index for pagination (0-based)
```

--------------------------------

### Run readiness probe with live staging profile

Source: https://mcp-atlassian.soomiles.com/docs/compatibility

Adds the --staging-dc-pat flag to the preceding command to call fixed Jira DC and Confluence DC issues/pages. Fails closed: forces read-only mode, exposes only jira_get_issue and confluence_get_page, disables retries, limits concurrency to one, and caps traffic at 30 requests per minute.

```bash
uv run python scripts/mcp_wire_probe.py \
  --server-command uv \
  --server-arg=run \
  --server-arg=mcp-atlassian \
  --staging-dc-pat

```

--------------------------------

### Configure working hours for SLA

Source: https://mcp-atlassian.soomiles.com/docs/advanced/sla-metrics

Enables business-hours-only SLA calculation. Sets the start and end times in 24-hour format and the working days (1=Monday, 7=Sunday).

```bash
# Enable working hours filtering
JIRA_SLA_WORKING_HOURS_ONLY=true

# Define business hours (24-hour format)
JIRA_SLA_WORKING_HOURS_START=09:00
JIRA_SLA_WORKING_HOURS_END=17:00

# Working days (1=Monday, 7=Sunday)
JIRA_SLA_WORKING_DAYS=1,2,3,4,5
```

--------------------------------

### Get Page Views

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-comments

Gets view statistics for a Confluence page.

```APIDOC
## Get Page Views

### Description
Gets view statistics for a Confluence page.

### Parameters
- **page_id** (string) - Required - Confluence page ID (numeric ID, can be found in the page URL). For example, in 'https://example.atlassian.net/wiki/spaces/TEAM/pages/123456789/Page+Title', the page ID is '123456789'.
- **include_title** (boolean) - Optional - Whether to fetch and include the page title.

### Example
```json
{"page_id": "12345678", "period": "lastMonth"}
```

### Notes
Useful for identifying popular or stale content. Available periods depend on your Confluence analytics configuration. Analytics features may require additional permissions on Server/DC.
```

--------------------------------

### Toolset filtering with TOOLSETS

Source: https://mcp-atlassian.soomiles.com/docs/configuration

Sets the TOOLSETS environment variable to enable groups of related tools. Examples show restricting to core tools (default), adding agile tools, using deprecated tools (legacy), combining default and legacy, and enabling all toolsets. Unknown toolset names are silently ignored; if all names are unknown, no tools are enabled (fail-closed).

```bash
# Restrict to core tools only (~35 tools across 6 core toolsets)
TOOLSETS=default

# Core tools plus agile boards/sprints
TOOLSETS=default,jira_agile

# Deprecated tools only, for migration compatibility
TOOLSETS=legacy

# Core tools plus deprecated tools during migration
TOOLSETS=default,legacy

# All toolsets (same as current default when TOOLSETS is unset)
TOOLSETS=all

```

--------------------------------

### Get Inline Comments

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-comments

Gets all inline comments for a Confluence page.

```APIDOC
## Get Inline Comments

### Description
Gets all inline comments for a Confluence page.

### Parameters
- **page_id** (string) - Required - The ID of the page to get inline comments from.

### Notes
Each inline comment includes `parent_comment_id`, `marker_ref`, `original_selection`, and `resolution_status` when Confluence provides those values.
```

--------------------------------

### Get Agile Boards

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-agile

Retrieves Jira agile boards by name, project key, or type. Supports fuzzy search by board name and can be combined with project key to narrow results.

```APIDOC
## Get Agile Boards

### Description
Get jira agile boards by name, project key, or type.

### Parameters
#### Query Parameters
- **board_name** (string) - Optional - The name of board, support fuzzy search
- **project_key** (string) - Optional - Jira project key (e.g., 'PROJ', 'ACV2')
- **board_type** (string) - Optional - The type of jira board (e.g., 'scrum', 'kanban')
- **start_at** (integer) - Optional - Starting index for pagination (0-based)
- **limit** (integer) - Optional - Maximum number of results (1-50)

### Request Example
{"board_name": "Sprint Board", "project_key": "PROJ", "board_type": "scrum"}

### Notes
Supports fuzzy search by board name. Combine with `project_key` to narrow results.
```

--------------------------------

### Enable minimal OAuth mode (uvx and Docker)

Source: https://mcp-atlassian.soomiles.com/docs/http-transport

Enable minimal OAuth mode for multi-tenant applications where each user connects to their own Atlassian cloud instance. Two equivalent commands are shown: one using uvx and one using Docker.

```bash
# Using uvx
ATLASSIAN_OAUTH_ENABLE=true uvx mcp-atlassian --transport streamable-http --port 9000

```

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

```

--------------------------------

### Get Page Restrictions

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-pages

Gets view and edit restrictions for a Confluence page.

```APIDOC
## Get Page Restrictions

### Description
Gets view and edit restrictions for a Confluence page.

### Parameters
- **page_id** (string) - Required - The ID of the page
```

--------------------------------

### Get Project Issue Types

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-search-fields

Get available issue types for a Jira project.

```APIDOC
## Get Project Issue Types

### Description
Get available issue types for a Jira project.

### Method
POST

### Endpoint
/get_project_issue_types

### Parameters
#### Request Body
- **project_key** (string) - Required - Jira project key (e.g., 'PROJ', 'JTEST')

### Request Example
{"project_key": "PROJ"}

### Response
#### Success Response (200)
- **issue_types** (array) - List of issue types. Each includes ID, name, description, subtask flag, and untranslated name when Jira provides one.

#### Response Example
{
  "issue_types": [
    {
      "id": "10000",
      "name": "Bug",
      "description": "A problem which impairs or prevents the functions of the product.",
      "subtask": false,
      "untranslated_name": "Bug"
    }
  ]
}

### Notes
The response includes each type's ID, name, description, subtask flag, and untranslated name when Jira provides one.
```

--------------------------------

### Get Field Options

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-search-fields

Get allowed option values for a custom field. Supports filtering and compact output.

```APIDOC
## Get Field Options

### Description
Get allowed option values for a custom field. Supports filtering and compact output.

### Method
POST

### Endpoint
/get_field_options

### Parameters
#### Request Body
- **field_id** (string) - Required - Custom field ID (e.g., 'customfield_10001'). Use jira_search_fields to find field IDs.
- **context_id** (string) - Optional - Field context ID (Cloud only). If omitted, auto-resolves to the global context.
- **project_key** (string) - Optional - Project key (required for Server/DC). Example: 'PROJ'
- **issue_type** (string) - Optional - Issue type name (required for Server/DC). Example: 'Bug'
- **contains** (string) - Optional - Case-insensitive substring filter on option values. Also matches child values in cascading selects.
- **return_limit** (integer) - Optional - Maximum number of results to return (applied after filtering).
- **values_only** (boolean) - Optional - If true, return only value strings in a compact JSON format instead of full option objects.

### Request Example
{"field_id": "customfield_10001", "contains": "high", "return_limit": 5, "values_only": true}

### Response
#### Success Response (200)
- **options** (array) - List of allowed option values. If values_only is true, returns an array of strings.

#### Response Example
{
  "options": ["High", "Highest"]
}

### Notes
Use `contains` to filter large option lists (e.g., hundreds of values). Combine with `values_only: true` for a compact response.
```

--------------------------------

### Configure IDE with Docker

Source: https://mcp-atlassian.soomiles.com/docs/installation

Configure an IDE to use MCP Atlassian via Docker. The args pass environment variable names to docker run, and the env block supplies the actual values.

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

--------------------------------

### Run MCP Inspector with uvx or local development version

Source: https://mcp-atlassian.soomiles.com/docs/troubleshooting

Launches the MCP Inspector to test the mcp-atlassian configuration interactively. The first command uses uvx, the second uses a local development version.

```bash
# With uvx
npx @modelcontextprotocol/inspector uvx mcp-atlassian

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

--------------------------------

### Docker with Environment File

Source: https://mcp-atlassian.soomiles.com/docs/configuration

Runs the mcp-atlassian server via Docker, loading environment variables from a specified env file. Replace the path to the env file with your actual path.

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

```

--------------------------------

### Environment variables for PAT placeholder values

Source: https://mcp-atlassian.soomiles.com/docs/http-transport

Set a URL and a non-empty server-side PAT value for each enabled service. These values let the server build its URL, SSL, and proxy configuration at startup. The PAT sent with each request replaces the corresponding server-side value for that API call.

```bash
JIRA_URL=https://jira.your-company.com
JIRA_PERSONAL_TOKEN=unused

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

```

--------------------------------

### Get Page request payload

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-pages

JSON payload for the Get Page tool, specifying a page ID and requesting metadata inclusion. To be passed as the tool input.

```json
{"page_id": "12345678", "include_metadata": true}
```

--------------------------------

### Configure IDE with uvx

Source: https://mcp-atlassian.soomiles.com/docs/installation

Configure Claude Desktop or Cursor to use MCP Atlassian via uvx. Edit the config file at the platform-specific path (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json, Linux: ~/.config/Claude/claude_desktop_config.json).

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

--------------------------------

### Get Issue Images

Source: https://mcp-atlassian.soomiles.com/docs/tools/jira-attachments

Get all images attached to a Jira issue as inline image content. Returns image attachments as inline ImageContent for LLM vision.

```APIDOC
## Get Issue Images

### Description
Get all images attached to a Jira issue as inline image content. Returns image attachments as inline ImageContent for LLM vision.

### Parameters
#### Request Body
- **issue_key** (string) - Required - Jira issue key (e.g., 'PROJ-123')

### Response
Returns image attachments as inline ImageContent for LLM vision.
```

--------------------------------

### Get development info for multiple issues

Source: https://mcp-atlassian.soomiles.com/docs/advanced/sla-metrics

Calls the `jira_get_issues_development_info` tool to get development info for multiple issues at once. The `issue_keys` field is a comma-separated list of issue keys.

```json
jira_get_issues_development_info: {
  "issue_keys": "PROJ-1,PROJ-2,PROJ-3"
}
```

--------------------------------

### Run latest mcp-atlassian with uvx

Source: https://mcp-atlassian.soomiles.com/docs/compatibility

Command to run the latest version of mcp-atlassian using uvx, recommended for resolving schema errors with Vertex AI/Google ADK.

```bash
uvx mcp-atlassian@latest
```

--------------------------------

### Update Page Section example payload

Source: https://mcp-atlassian.soomiles.com/docs/tools/confluence-pages

Example payload for updating a single section of a Confluence page. The heading_text must match exactly (case-sensitive, no emoji) and new_content excludes the heading. If the heading is not found, a ValueError is raised without updating the page.

```json
{"page_id": "12345678", "heading_text": "Weekly Update", "new_content": "- Shipped v2.1\n- Started v2.2 planning", "version_comment": "Weekly sync"}
```