> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-atlassian.soomiles.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

<Tabs>
  <Tab title="Confluence Only">
    ```json theme={null}
    {
      "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"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Jira Only">
    ```json theme={null}
    {
      "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"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## 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](#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`)                                                                                                                                               |
| `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](https://github.com/sooperset/mcp-atlassian/blob/main/.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.

```bash theme={null}
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.
</Note>

## Tool Filtering

Control which tools are available:

```bash theme={null}
# 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:

```bash theme={null}
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.

```bash theme={null}
# 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:

```bash theme={null}
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.
</Warning>

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

See [Toolset Groups](/docs/tools-reference#toolset-groups) for the full list of available toolsets.