jira-confluence-mcp

jira-confluence-mcp — install, secure & operate the mcp-atlassian MCP server

Scope: getting sooperset/mcp-atlassian — the MCP server that gives an agent Jira/Confluence tools — connected, hardened, and debugged, including air-gapped. This is the setup/ops layer: the knowledge that is invisible at tool-call time.

Hard boundary — what this skill does NOT do. Once the server is connected, it self-documents its full tool set at runtime (72 at v0.21.1; v0.22.0/v0.23.0 added more — the live list is the count) (names, params, schemas) over the MCP protocol — so using the tools (jira_search, jira_create_issue, jira_transition_issue, …) needs no skill; just call them. For exhaustive tool/JQL/CQL docs, the project publishes an LLM-readable https://mcp-atlassian.soomiles.com/llms-full.txt — fetch it on demand instead of duplicating it here. Sibling skills: jira-cli (the jira CLI as an alternative execution path) and jira-best-practices (how to use Jira well — hierarchy, lean config). This skill is only the install/auth/hardening/air-gap/troubleshooting that those don't cover and the live MCP can't surface.

Self-hosted Data Center is the default here. Where Cloud differs, it's flagged.

The #1 gotcha: Data Center auth is a PAT, not username+token

Claude's base instinct is the Cloud pattern — and it fails on Data Center.

DC PATs: created at profile → Personal Access Tokens; max 10 per user; set an expiry. Full auth matrix (OAuth 2.0, BYOT, multi-cloud) + the complete env-var catalog: references/auth-config.md.

Enable Jira, Confluence, or both (the #1 setup miss)

mcp-atlassian runs a separate client per product, each gated on its own *_URL + auth. Supply only JIRA_* and you get only jira_* tools — Jira's vars do not carry over to Confluence (and vice-versa), and the missing product's tools just don't appear, with no error. To add Confluence:

TOOLSETS=all/default already covers both products, so missing tools mean missing creds, not a toolset problem. After any env change, reconnect (/mcp → reconnect, or restart — env is read only at spawn) and verify with claude mcp list + the tool count. Symptom row: references/troubleshooting.md.

Install & connect (Claude Code)

uvx is the runner for a connected host; Docker/image is the path for production and air-gap. Add it to Claude Code with claude mcp add (the upstream docs only show Claude-Desktop/Cursor JSON):

# Data Center, Jira only (add CONFLUENCE_URL + CONFLUENCE_PERSONAL_TOKEN for Confluence too):
claude mcp add mcp-atlassian \
  -e JIRA_URL=https://jira.internal.company.com \
  -e JIRA_PERSONAL_TOKEN=<pat> \
  -- uvx mcp-atlassian

# Cloud, BOTH products — same email + token; Confluence URL ends /wiki:
claude mcp add mcp-atlassian \
  -e JIRA_URL=https://your-co.atlassian.net -e CONFLUENCE_URL=https://your-co.atlassian.net/wiki \
  -e [email protected] -e [email protected] \
  -e JIRA_API_TOKEN=<token> -e CONFLUENCE_API_TOKEN=<token> \
  -- uvx mcp-atlassian

Other install methods (pip, uv, source) exist but pull from PyPI — see references/air-gapped.md for why that matters offline.

TLS / internal CA — add the CA or disable verification

Self-hosted Jira usually presents an internal-CA or self-signed cert. mcp-atlassian trusts the OS trust store by default (via truststore), so a CA already in the host's Windows/macOS/Linux store works with no config. Two fixes when it doesn't (e.g. inside a container, which only has the stock bundle):

• Preferred — trust the CA (keeps TLS verification on):
  • uvx / host install: put the internal CA in the OS trust store (update-ca-certificates on Linux), or point at a bundle with REQUESTS_CA_BUNDLE=/path/ca.pem / SSL_CERT_FILE=/path/ca.pem.
  • Docker: mount the CA in and refresh the bundle — -v /etc/pki/internal-ca.crt:/usr/local/share/ca-certificates/internal-ca.crt:ro (Alpine image: the cert dir is /usr/local/share/ca-certificates/; the bundled python:3.13-alpine won't have the internal CA otherwise).
  • mTLS: JIRA_CLIENT_CERT=/path/cert.pem + JIRA_CLIENT_KEY=/path/key.pem.
• Escape hatch — skip verification (only when trusting the CA isn't practical):
  • JIRA_SSL_VERIFY=false (and CONFLUENCE_SSL_VERIFY=false). Disables cert checking for that service. Acceptable on a trusted internal network; flag it as a deliberate downgrade.
  • To fall back to the bundled certifi CA instead of the OS store: MCP_ATLASSIAN_USE_SYSTEM_TRUSTSTORE=false.

The container-CA step is the most common air-gap surprise — a self-contained image still doesn't trust the internal CA. Full detail in references/air-gapped.md.

Air-gapped install (short version)

A full git mirror of the repo is NOT enough — the dependency wheels live on PyPI, not in git. If the environment can serve container images, the clean path is to mirror the prebuilt image by digest (it bakes Python + all deps in — no PyPI, no git needed at install or run):

# 1. resolve + mirror the prebuilt image, pinned by digest (supply-chain hygiene)
skopeo copy --all \
  docker://ghcr.io/sooperset/mcp-atlassian:v0.23.0 \
  docker://harbor.internal/mirror/mcp-atlassian:v0.23.0
# 2. connect (stdio needs -i); mount the internal CA so TLS verifies
claude mcp add mcp-atlassian \
  -e JIRA_URL=https://jira.internal.company.com \
  -e JIRA_PERSONAL_TOKEN=<pat> \
  -- docker run -i --rm -e JIRA_URL -e JIRA_PERSONAL_TOKEN \
       -v /etc/pki/internal-ca.crt:/usr/local/share/ca-certificates/internal-ca.crt:ro \
       harbor.internal/mirror/mcp-atlassian@sha256:<digest>

Critical nuance: mirror the prebuilt image (no PyPI). Building the image from a git mirror still needs a PyPI index for uv sync plus the two base images mirrored. The 3-artifact-type breakdown, the build-from-source path, and digest-pinning are in references/air-gapped.md.

Hardening (do this by default)

The server exposes 72 write-capable tools; scope it deliberately.

• READ_ONLY_MODE=true — disables all write tools regardless of other settings. Use for read/report-only agents.
• TOOLSETS — group-level control (15 Jira + 6 Confluence toolsets). TOOLSETS=default ≈ 23 core tools; add extras like default,jira_agile. ENABLED_TOOLS allow-lists individual tools; the two intersect.
• JIRA_PROJECTS_FILTER / CONFLUENCE_SPACES_FILTER — limit blast radius to named projects/spaces.
• Version gotcha — now shipped: v0.22.0 (2026-07-10) flipped the default from all-tools → 6 core toolsets only. On any build ≥ v0.22.0 you must set TOOLSETS=all explicitly to keep the old behaviour; unknown toolset names are silently ignored (all-unknown = fail-closed, zero tools).
• ⚠ v0.22.0 also closed a critical transport hole. Before it, an unauthenticated streamable-http request fell back to the operator's global credentials; now such requests get 401, with the old behaviour opt-in via ALLOW_GLOBAL_CRED_FALLBACK (default off). stdio deployments were never exposed. Do not set that variable to silence a post-upgrade 401 — it restores the vulnerability. v0.22.0 also confines attachment/content_file paths to the server's working directory (use the new content_base64 input instead of absolute paths). See references/hardening.md.

Toolset tables + the read-only/filter mechanics: references/hardening.md.

Cloud vs Data Center divergence (so advice doesn't mislead)

Troubleshooting (pointer)

401 (PAT vs token), 403 (perms / READ_ONLY_MODE blocking writes), customfield_XXXXX not found (→ jira_search_fields), 429 (→ batch tools / ENABLED_TOOLS), SSL, timeouts, and verbose-logging/MCP Inspector debugging: references/troubleshooting.md.

What to read next

For tool usage and exhaustive refer

Content truncated.