Configuration

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

Note

Installing this fork — use pip install mcp-atlassian-ry or uvx --from mcp-atlassian-ry mcp-atlassian. The CLI command is mcp-atlassian (same as upstream) — the --from flag makes clear you are running this fork and not the upstream package.

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-ry": {
      "command": "uvx",
      "args": [
        "--from", "mcp-atlassian-ry",
        "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"
      }
    }
  }
}

Single Service Configuration¶

Confluence OnlyJira Only

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

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`)
`MCP_ATLASSIAN_USE_SYSTEM_TRUSTSTORE`	Use OS native trust store (`true`/`false`, default: `true`)

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`, `all`, `default,jira_agile`

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

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.

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.

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 (~23 tools across 6 core toolsets)
TOOLSETS=default

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

# 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

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.

Warning

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

Note

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.

Requirements Yogi¶

Note

Requirements Yogi tools are available in this fork of MCP Atlassian. They require the Requirements Yogi app to be installed in your Confluence instance.

Requirements Yogi reuses Confluence authentication automatically — no additional credentials are needed. Configure it the same way as Confluence (see Connection Settings above).

Requirements Yogi Filtering¶

Variable	Description	Example
`REQUIREMENT_YOGI_SPACES_FILTER`	Limit access to specific Confluence spaces	`LUNA,NOVA,DEV`

When set, only requirements from the listed space keys are accessible. This is independent of CONFLUENCE_SPACES_FILTER.

# Allow Requirements Yogi access only in these spaces
REQUIREMENT_YOGI_SPACES_FILTER=LUNA,NOVA,DEV

Enabling Requirements Yogi Tools¶

Requirements Yogi tools belong to the requirement_yogi toolset (not a core toolset):

# Enable alongside core tools
TOOLSETS=default,requirement_yogi

# Enable all toolsets including Requirements Yogi
TOOLSETS=all

See Requirements Yogi Tools for the full tool reference and Search Syntax for the query language.