MCP Atlassian

https://mcp-atlassian.soomiles.com
Admin
MCP Atlassian is a Model Context Protocol server that connects AI assistants to Jira and Confluence...
Tokens:69,880
Snippets:481
Trust Score:2.7
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### 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
```

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

### 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_]*$
```

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

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

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

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

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

### 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."}
```

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

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

```

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

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

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

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

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

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

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

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

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

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

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

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

```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```

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

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

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

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

```

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

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

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

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

```

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

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

```

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

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

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

### 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())

```

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

### 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')
```

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

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

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

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

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

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

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

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

```
Tokens:
Raw