---
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)
```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"
}
}
}
}
```
### Docker with Environment File
```json
{
"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
{
"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
{
"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
{
"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`) |
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
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
# 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
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
# 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
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.
