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 72 tools at runtime (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.

| Deployment | Required env vars | |---|---| | Data Center / Server | JIRA_URL + JIRA_PERSONAL_TOKEN (a Personal Access Token). No username. | | Cloud | JIRA_URL + JIRA_USERNAME (email) + JIRA_API_TOKEN |

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:

| | Cloud | Data Center | |---|---|---| | URL | CONFLUENCE_URL=https://.atlassian.net/wiki — note the /wiki (Jira is the bare domain) | its own host / context path, e.g. https://confluence.internal.company.com | | Auth | CONFLUENCE_USERNAME + CONFLUENCE_API_TOKEN — the same email + token as Jira (Cloud API tokens are account-scoped; reuse the Jira values) | CONFLUENCE_PERSONAL_TOKEN (a PAT, like Jira) |

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= \
  -- 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 JIRA_USERNAME=you@co.com -e CONFLUENCE_USERNAME=you@co.com \
  -e JIRA_API_TOKEN= -e CONFLUENCE_API_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.21.1 \
  docker://harbor.internal/mirror/mcp-atlassian:v0.21.1
# 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= \
  -- 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:

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: in v0.22.0 the default flips from all-72-tools → 6 core toolsets only. To keep current behavior set TOOLSETS=all explicitly; unknown toolset names are silently ignored (all-unknown = fail-closed, zero tools).

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

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

| Aspect | Cloud | Data Center | |---|---|---| | Auth | username + API token / OAuth 3LO | PAT (JIRA_PERSONAL_TOKEN) / Application-Links OAuth | | Content format | ADF | wiki markup (both auto-converted from Markdown by the tools) | | User identifiers | accountId | username / userKey | | Tools unavailable on DC | — | jira_batch_get_changelogs, proforma forms, confluence_get_page_views (Cloud-only APIs) | | Custom field IDs | per-instance | per-instance — differ from Cloud; discover via jira_search_fields | | Rate limit | ~100 req/min | instance-dependent |

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

| File | Read when… | |---|---| | references/air-gapped.md | Installing offline — the 3 artifact types, prebuilt-image mirror, build-from-source caveats, digest pinning, in-container CA | | references/auth-config.md | Choosing/setting auth (DC PAT, Cloud token, OAuth, BYOT, multi-cloud) + the full env-var catalog (SSL, proxy, headers, timeouts) | | references/hardening.md | Restricting tools — READ_ONLY_MODE, the 15+6 toolset tables, ENABLED_TOOLS, project/space filters, the v0.22 default change | | references/troubleshooting.md | A specific failure — 401/403, field-not-found, rate limits, SSL, timeouts, debug logging, MCP Inspector | | references/sources.md | Verifying/freshening a claim — per-row source + tier + verify date |

For tool usage and exhaustive references, go to the live MCP (tool schemas at runtime) and llms-full.txt — not this skill.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: air-gapped
• Source: air-gapped/skills
• License: MIT

Install and usage instructions live in the source repository linked above.