Skip to content

configuration.mdx

Latest commit

 

History

History
257 lines (211 loc) · 8.38 KB

configuration.mdx

File metadata and controls

257 lines (211 loc) · 8.38 KB
Raw
title Configuration
description Configure MCP Atlassian for Claude Desktop, Cursor, Windsurf, and VS Code with environment variables

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

Single Service Configuration

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

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

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.