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)

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

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

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

For mTLS, replace the personal token variables with client certificate variables. Use a combined certificate-and-private-key PEM in *_CLIENT_CERT, or use *_CLIENT_CERT and the matching *_CLIENT_KEY for separate files:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_CLIENT_CERT": "/etc/mcp-atlassian/jira-client-cert.pem",
        "JIRA_CLIENT_KEY": "/etc/mcp-atlassian/jira-client-key.pem",
        "CONFLUENCE_URL": "https://confluence.your-company.com/wiki",
        "CONFLUENCE_CLIENT_CERT": "/etc/mcp-atlassian/confluence-client-combined.pem"
      }
    }
  }
}

JIRA_CLIENT_CERT and CONFLUENCE_CLIENT_CERT can point to combined PEM files. If the private key is separate, set JIRA_CLIENT_KEY or CONFLUENCE_CLIENT_KEY as appropriate. Encrypted private keys aren’t supported by the requests library, so decrypt them before starting MCP Atlassian instead of setting JIRA_CLIENT_KEY_PASSWORD or CONFLUENCE_CLIENT_KEY_PASSWORD.

Single Service Configuration

Confluence Only
Jira Only

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

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

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_CLIENT_CERT`	Jira mTLS client certificate PEM path (Server/DC), combined or certificate-only
`JIRA_CLIENT_KEY`	Jira mTLS private key PEM path when the certificate is separate (Server/DC)
`JIRA_CLIENT_KEY_PASSWORD`	Not supported for encrypted private keys; decrypt the key before use
`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_CLIENT_CERT`	Confluence mTLS client certificate PEM path (Server/DC), combined or certificate-only
`CONFLUENCE_CLIENT_KEY`	Confluence mTLS private key PEM path when the certificate is separate (Server/DC)
`CONFLUENCE_CLIENT_KEY_PASSWORD`	Not supported for encrypted private keys; decrypt the key before use
`CONFLUENCE_SSL_VERIFY`	SSL verification (`true`/`false`)
`MCP_ATLASSIAN_USE_SYSTEM_TRUSTSTORE`	Use OS native trust store (`true`/`false`, default: `true`)
`MCP_ATLASSIAN_VALIDATION_CACHE_TTL`	Multi-user credential validation cache lifetime in seconds (`0` disables, default: `300`)
`MCP_ATLASSIAN_VALIDATION_CACHE_MAXSIZE`	Maximum cached multi-user credential validations (default: `100`)

Encrypted private keys are not supported. Setting JIRA_CLIENT_KEY_PASSWORD or CONFLUENCE_CLIENT_KEY_PASSWORD to a non-empty value will raise a configuration error at startup. Decrypt the key first:

openssl rsa -in encrypted.key -out decrypted.key

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`
`TOOLSETS`	Enable tool groups (see Toolset Filtering)	`default`, `legacy`, `all`, `default,jira_agile`

Jira Key Validation

Jira tools validate their issue_key / project_key arguments before calling the API. The defaults match the Cloud key format, which cannot be changed. On Server/Data Center the format is an instance setting (jira.projectkey.pattern), so widen these patterns if your instance allows keys the defaults reject — a leading digit, a single character, or lowercase. An invalid regex is ignored (a warning is logged) and the default is kept. Both are read once at startup.

Variable	Description
`JIRA_ISSUE_KEY_PATTERN`	Regex accepted for `issue_key` arguments (default: `^[A-Z][A-Z0-9_]+-\d+(?:-\d+)*$`)
`JIRA_PROJECT_KEY_PATTERN`	Regex accepted for `project_key` arguments (default: `^[A-Z][A-Z0-9_]+$`)

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

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`)
`CONFLUENCE_ATTACHMENT_DOWNLOAD_USE_V1`	Download Confluence attachments via the v1 REST endpoint instead of the legacy `/download/` link (removed on Cloud). Unset = auto (v1 on Cloud, legacy on Server/DC); `true`/`false` to force.
`ATLASSIAN_OAUTH_PROXY_ENABLE`	Enable OAuth proxy + DCR + `/.well-known/*` routes (`true`/`false`)
`PUBLIC_BASE_URL`	Public base URL for OAuth discovery metadata
`ATLASSIAN_OAUTH_ALLOWED_CLIENT_REDIRECT_URIS`	Comma-separated allowed redirect URI patterns for DCR clients
`ATLASSIAN_OAUTH_ALLOWED_GRANT_TYPES`	Comma-separated grant types allowed during DCR
`ATLASSIAN_OAUTH_REQUIRE_CONSENT`	Require local consent page before upstream redirect (`true`/`false`)
`IGNORE_HEADER_AUTH`	Bypass proxy-injected auth headers. For GCP Cloud Run, AWS ALB deployments where load balancers inject Authorization headers (`true`/`false`)

See .env.example for all available options.

HTTP Hardening

These optional safeguards are useful for protecting self-hosted Server/Data Center instances from runaway request loops. They are disabled by default.

Variable	Description
`ATLASSIAN_RETRY_TOTAL`	Enable retries for transient `429/502/503/504` responses and connection errors. `0` or unset disables retries.
`ATLASSIAN_RETRY_BACKOFF`	Retry exponential backoff factor in seconds (default: `1.0` when retries are enabled).
`ATLASSIAN_RETRY_INCLUDE_WRITES`	Also retry write methods (`POST`/`PUT`/`PATCH`/`DELETE`). Use only when writes are known to be idempotent.
`ATLASSIAN_RETRY_IGNORE_RETRY_AFTER`	Ignore the server’s `Retry-After` header and use exponential backoff instead. Enable this for gateways that emit bogus values such as `Retry-After: 0`.
`ATLASSIAN_MAX_CONCURRENT_REQUESTS`	Process-wide cap for concurrent Jira and Confluence requests. `0` or unset disables the cap.
`ATLASSIAN_REQUESTS_PER_SECOND`	Process-wide outbound request rate limit. `0` or unset disables the limit.
`ATLASSIAN_MAX_PAGINATION_LIMIT`	Clamp user-supplied page sizes for high-fanout list/search calls. `0` or unset disables clamping.
`ATLASSIAN_CIRCUIT_BREAKER_THRESHOLD`	Open a process-wide circuit breaker after this many consecutive `429/503` responses. `0` or unset disables it.
`ATLASSIAN_CIRCUIT_BREAKER_COOLDOWN`	Circuit breaker cooldown in seconds before allowing a probe request (default: `30.0`).

Proxy Configuration

MCP Atlassian supports routing API requests through HTTP/HTTPS/SOCKS proxies, with optional PAC/WPAD auto-configuration.

Variable	Description
`HTTP_PROXY`	Global HTTP proxy URL
`HTTPS_PROXY`	Global HTTPS proxy URL
`SOCKS_PROXY`	Global SOCKS proxy URL
`NO_PROXY`	Global hosts to bypass proxy
`ATLASSIAN_PROXY_WPAD_ENABLE`	Enable global PAC/WPAD evaluation (`true`/`false`)
`ATLASSIAN_PROXY_WPAD_URL`	Global PAC URL (defaults to `http://wpad/wpad.dat` when enabled)
`JIRA_HTTP_PROXY`, `JIRA_HTTPS_PROXY`, `JIRA_SOCKS_PROXY`, `JIRA_NO_PROXY`	Jira-specific explicit proxy overrides
`JIRA_PROXY_WPAD_ENABLE`, `JIRA_PROXY_WPAD_URL`	Jira-specific PAC/WPAD overrides
`CONFLUENCE_HTTP_PROXY`, `CONFLUENCE_HTTPS_PROXY`, `CONFLUENCE_SOCKS_PROXY`, `CONFLUENCE_NO_PROXY`	Confluence-specific explicit proxy overrides
`CONFLUENCE_PROXY_WPAD_ENABLE`, `CONFLUENCE_PROXY_WPAD_URL`	Confluence-specific PAC/WPAD overrides

Service-specific variables override global ones. PAC/WPAD is opt-in and is only evaluated when no explicit proxy is configured for that service. PAC/WPAD support is provided by the optional wpad extra. Install it with pip install "mcp-atlassian[wpad]" or uv add "mcp-atlassian[wpad]" before enabling the feature. The published Docker image includes this extra.

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
`JIRA_PASSTHROUGH_HEADERS`	Incoming MCP request header names to pass through to Jira requests
`CONFLUENCE_PASSTHROUGH_HEADERS`	Incoming MCP request header names to pass through to Confluence requests

Format: Static custom headers use comma-separated key=value pairs. Passthrough headers use comma-separated header names.

JIRA_CUSTOM_HEADERS=X-Forwarded-User=service-account,X-Custom-Auth=token
CONFLUENCE_CUSTOM_HEADERS=X-Service=mcp-integration,X-ALB-Token=secret

# Header names only. Values are read from each incoming MCP HTTP request.
JIRA_PASSTHROUGH_HEADERS=X-SSO-User,X-Request-ID
CONFLUENCE_PASSTHROUGH_HEADERS=X-SSO-User,X-Request-ID

Passthrough headers are request-scoped and only apply to HTTP transports. If a passthrough header name conflicts with a static custom header, the incoming request header value is used for that request. Only configure headers that are set by a trusted proxy or gateway. Clients can control any passthrough header they are allowed to send to the MCP endpoint. When external auth uses a client-supplied Jira or Confluence URL, configure MCP_ALLOWED_URL_DOMAINS; dynamic URLs are rejected without this allowlist so trusted session headers cannot be forwarded to an attacker-controlled host.

Header values are masked in debug logs for security.

Tool Filtering

Control which tools are available:

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

uvx mcp-atlassian --enabled-tools "confluence_search,jira_get_issue"

Toolset Filtering

Toolsets provide group-level tool control. Instead of listing individual tool names, enable entire groups of related tools at once using the TOOLSETS environment variable.

# 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

Command-line alternative:

uvx mcp-atlassian --toolsets "default,jira_agile"

Core toolsets (included with TOOLSETS=default): jira_issues, jira_fields, jira_comments, jira_transitions, confluence_pages, confluence_comments The opt-in legacy toolset contains deprecated tools retained while users migrate to their replacement tools. Use TOOLSETS=legacy to expose only those tools, or combine it with another selection such as TOOLSETS=default,legacy. It is not included in TOOLSETS=default. When both TOOLSETS and ENABLED_TOOLS are set, they intersect — a tool must pass both filters. If TOOLSETS is not set, all toolsets are currently enabled.

In v0.22.0, the default will change from all toolsets to 6 core toolsets only. Set TOOLSETS=all explicitly to preserve current behavior.

Unknown toolset names are silently ignored. If all names are unknown, no tools are enabled (fail-closed behavior to prevent accidental exposure).

See Toolset Groups for the full list of available toolsets.

Getting Started

Usage

Guides

Jira Tools

Confluence Tools

Advanced

Help

IDE Integration

Configuration File Locations

Basic Configuration (uvx)

Docker with Environment File

Server/Data Center Configuration

Single Service Configuration

Environment Variables

Connection Settings

Filtering Options

Jira Key Validation

Server Options

HTTP Hardening

Proxy Configuration

Custom HTTP Headers

Tool Filtering

Toolset Filtering

​IDE Integration

​Configuration File Locations

​Basic Configuration (uvx)

​Docker with Environment File

​Server/Data Center Configuration

​Single Service Configuration

​Environment Variables

​Connection Settings

​Filtering Options

​Jira Key Validation

​Server Options

​HTTP Hardening

​Proxy Configuration

​Custom HTTP Headers

​Tool Filtering

​Toolset Filtering

IDE Integration

Configuration File Locations

Basic Configuration (uvx)

Docker with Environment File

Server/Data Center Configuration

Single Service Configuration

Environment Variables

Connection Settings

Filtering Options

Jira Key Validation

Server Options

HTTP Hardening

Proxy Configuration

Custom HTTP Headers

Tool Filtering

Toolset Filtering