mcp-atlassian/.env.example at main · suparious/mcp-atlassian · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
# MCP-ATLASSIAN CONFIGURATION EXAMPLE
# -------------------------------------
# Copy this file to .env and fill in your details.
# - Do not use double quotes for string values in this file, unless the value itself contains spaces.

# =============================================
# ESSENTIAL ATLASSIAN INSTANCE URLS
# =============================================
# REQUIRED: Replace with your Atlassian instance URLs.
# Example Cloud: https://your-company.atlassian.net
# Example Server/DC: https://jira.your-internal-domain.com
JIRA_URL=https://your-company.atlassian.net
# Example Cloud: https://your-company.atlassian.net/wiki
# Example Server/DC: https://confluence.your-internal-domain.com
CONFLUENCE_URL=https://your-company.atlassian.net/wiki

# =============================================
# AUTHENTICATION: CHOOSE ONE METHOD PER PRODUCT (Jira/Confluence)
# =============================================
# mcp-atlassian will attempt to auto-detect the auth method based on the credentials you provide below.
# Precedence for auto-detection:
#   1. Username/API Token (Basic Auth) - Recommended for Cloud
#   2. Personal Access Token (if URL is Server/DC and PAT is set)
#   3. OAuth BYOT (if ATLASSIAN_OAUTH_CLOUD_ID and ATLASSIAN_OAUTH_ACCESS_TOKEN are set)
#   4. OAuth Standard (if OAuth Client ID/Secret are set)

# --- METHOD 1: API TOKEN (Recommended for Atlassian Cloud) ---
# Get API tokens from: https://id.atlassian.com/manage-profile/security/api-tokens
# This is the simplest and most reliable authentication method for Cloud deployments.
#JIRA_USERNAME=your.email@example.com
#JIRA_API_TOKEN=your_jira_api_token

#CONFLUENCE_USERNAME=your.email@example.com
#CONFLUENCE_API_TOKEN=your_confluence_api_token

# --- METHOD 2: PERSONAL ACCESS TOKEN (PAT) (Server / Data Center - Recommended) ---
# Create PATs in your Jira/Confluence profile settings (usually under "Personal Access Tokens").
#JIRA_PERSONAL_TOKEN=your_jira_personal_access_token

#CONFLUENCE_PERSONAL_TOKEN=your_confluence_personal_access_token

# --- METHOD 3: USERNAME/PASSWORD (Server / Data Center - Uses Basic Authentication) ---
#JIRA_USERNAME=your_server_dc_username
#JIRA_API_TOKEN=your_jira_server_dc_password # For Server/DC Basic Auth, API_TOKEN holds the actual password

#CONFLUENCE_USERNAME=your_server_dc_username
#CONFLUENCE_API_TOKEN=your_confluence_server_dc_password

# --- METHOD 4: OAUTH 2.0 (Advanced - Atlassian Cloud Only) ---
# OAuth 2.0 provides enhanced security but is more complex to set up.
# For most users, Method 1 (API Token) is simpler and sufficient.
# 1. Create an OAuth 2.0 (3LO) app in Atlassian Developer Console:
#    https://developer.atlassian.com/console/myapps/
# 2. Set the Callback/Redirect URI in your app (e.g., http://localhost:8080/callback).
# 3. Grant necessary scopes (see ATLASSIAN_OAUTH_SCOPE below).
# 4. Run 'mcp-atlassian --oauth-setup -v' (or 'uvx mcp-atlassian@latest --oauth-setup -v').
#    This wizard will guide you through authorization and provide your ATLASSIAN_OAUTH_CLOUD_ID.
#    Tokens are stored securely (keyring or a local file in ~/.mcp-atlassian/).

# Required for --oauth-setup and for the server to use OAuth:
#ATLASSIAN_OAUTH_CLIENT_ID=your_oauth_client_id
#ATLASSIAN_OAUTH_CLIENT_SECRET=your_oauth_client_secret
#ATLASSIAN_OAUTH_REDIRECT_URI=http://localhost:8080/callback # Must match your app's redirect URI
#ATLASSIAN_OAUTH_SCOPE=read:jira-work write:jira-work read:confluence-space.summary read:confluence-content.all write:confluence-content offline_access # IMPORTANT: 'offline_access' is crucial for refresh tokens

# Required for the server AFTER running --oauth-setup (this ID is printed by the setup wizard):
#ATLASSIAN_OAUTH_CLOUD_ID=your_atlassian_cloud_id_from_oauth_setup

# --- METHOD 5: BRING YOUR OWN TOKEN (BYOT) OAUTH (Advanced - Atlassian Cloud Only) ---
# Use this method when you have an externally managed OAuth access token.
# This is useful for integration with larger systems (e.g., MCP Gateway) that manage OAuth tokens.
# No token refresh will be performed - the external system is responsible for token management.
#ATLASSIAN_OAUTH_CLOUD_ID=your_atlassian_cloud_id
#ATLASSIAN_OAUTH_ACCESS_TOKEN=your_pre_existing_oauth_access_token

# =============================================
# SERVER/DATA CENTER SPECIFIC SETTINGS
# =============================================
# Only applicable if your JIRA_URL/CONFLUENCE_URL points to a Server/DC instance (not *.atlassian.net).
# Default is true. Set to false if using self-signed certificates (not recommended for production environments).
#JIRA_SSL_VERIFY=true
#CONFLUENCE_SSL_VERIFY=true


# =============================================
# OPTIONAL CONFIGURATION
# =============================================

# --- General Server Settings ---
# Transport mode for the MCP server. Default is 'stdio'.
# Options: stdio, sse
#TRANSPORT=stdio
# Port for 'sse' transport. Default is 8000.
#PORT=8000
# Host for 'sse' transport. Default is '0.0.0.0'.
#HOST=0.0.0.0

# --- Read-Only Mode ---
# Disables all write operations (create, update, delete). Default is false.
#READ_ONLY_MODE=false

# --- Logging Verbosity ---
# MCP_VERBOSE=true        # Enables INFO level logging (equivalent to 'mcp-atlassian -v')
# MCP_VERY_VERBOSE=true   # Enables DEBUG level logging (equivalent to 'mcp-atlassian -vv')
# MCP_LOGGING_STDOUT=true # Enables logging to stdout (logging.StreamHandler defaults to stderr)
# Default logging level is WARNING (minimal output).

# --- Tool Filtering ---
# Comma-separated list of tool names to enable. If not set, all tools are enabled
# (subject to read-only mode and configured services).
# Example: ENABLED_TOOLS=confluence_search,jira_get_issue
#ENABLED_TOOLS=

# --- Content Filtering ---
# Optional: Comma-separated list of Confluence space keys to limit searches and other operations to.
#CONFLUENCE_SPACES_FILTER=DEV,TEAM,DOC
# Optional: Comma-separated list of Jira project keys to limit searches and other operations to.
#JIRA_PROJECTS_FILTER=PROJ,DEVOPS

# --- Proxy Configuration (Advanced) ---
# Global proxy settings (applies to both Jira and Confluence unless overridden by service-specific proxy settings below).
#HTTP_PROXY=http://proxy.example.com:8080
#HTTPS_PROXY=https://user:pass@proxy.example.com:8443 # Credentials can be included
#SOCKS_PROXY=socks5://proxy.example.com:1080 # Requires 'requests[socks]' to be installed
#NO_PROXY=localhost,127.0.0.1,.internal.example.com # Comma-separated list of hosts/domains to bypass proxy

# Jira-specific proxy settings (these override global proxy settings for Jira requests).
#JIRA_HTTP_PROXY=http://jira-proxy.example.com:8080
#JIRA_HTTPS_PROXY=https://jira-proxy.example.com:8443
#JIRA_SOCKS_PROXY=socks5://jira-proxy.example.com:1080
#JIRA_NO_PROXY=localhost,127.0.0.1,.internal.jira.com

# Confluence-specific proxy settings (these override global proxy settings for Confluence requests).
#CONFLUENCE_HTTP_PROXY=http://confluence-proxy.example.com:8080
#CONFLUENCE_HTTPS_PROXY=https://confluence-proxy.example.com:8443
#CONFLUENCE_SOCKS_PROXY=socks5://confluence-proxy.example.com:1080
#CONFLUENCE_NO_PROXY=localhost,127.0.0.1,.internal.confluence.com

# --- Custom HTTP Headers (Advanced) ---
# Jira-specific custom headers.
#JIRA_CUSTOM_HEADERS=X-Jira-Service=mcp-integration,X-Custom-Auth=jira-token,X-Forwarded-User=service-account

# Confluence-specific custom headers.
#CONFLUENCE_CUSTOM_HEADERS=X-Confluence-Service=mcp-integration,X-Custom-Auth=confluence-token,X-ALB-Token=secret-token