Connect Claude Code to Self-Hosted Jira and Confluence

Last updated: October 2026

We are going to connect Claude Code to a self-hosted Jira and Confluence instance, the kind that sits behind a corporate network on an internal address rather than an atlassian.net one. By the end you will be able to ask Claude, in your own terminal, to list your Jira projects and read your Confluence pages, using a token you created and with writes switched off for the first run. The command you have seen in every tutorial and video will not do this, and understanding why is the first step rather than a footnote.

What you need before starting

• Claude Code installed and authenticated, on a machine that can reach your internal Jira and Confluence (on the corporate network or VPN)
• An account on both instances with permission to create a Personal Access Token
• Either Docker, or Python 3.12 with uv, allowed to run on that machine
• Your IT or security contact reachable, because two of the steps below are their decision and not yours
• About an hour, most of which is waiting for answers rather than typing

Step 1: Work out which Atlassian you are actually on

This single fact decides the whole path, and getting it wrong is the reason most people give up. Look at the URL you use to open a ticket.

https://yourcompany.atlassian.net/jira/...   ->  Atlassian Cloud
https://jira.yourcompany.com/browse/...      ->  Server or Data Center

Anything that is not atlassian.net is almost certainly Server or Data Center, which means self-hosted, which means it lives inside your network. You can confirm it in the product under Help, then About.

Here is why it matters. The official Atlassian MCP server, along with every connector in Claude's connector directory and everything in Cowork's connector list, is a hosted bridge to Atlassian Cloud. Those connectors do not run on your laptop even when the app does. They reach the target service from Anthropic's cloud, over the public internet, from Anthropic's own IP ranges. Anthropic's documentation states the consequence directly: a server on a private network, behind a VPN, or behind a firewall will not connect, even if you can open it fine in your own browser.

So the copy-paste line you have seen everywhere, the one that adds the hosted Atlassian endpoint over SSE, connects successfully to Atlassian's cloud bridge and then finds nothing of yours behind it. You get a working connection and 404s on every page you ask for, which is a genuinely confusing failure because nothing announces itself as broken. That hosted SSE endpoint was also scheduled for retirement after June 2026, so some of those tutorials now fail at an earlier step for an unrelated reason.

The path that does work is the opposite shape. Instead of a bridge in the cloud reaching in, you run a small server on your own machine that reaches out to Jira using your machine's network position. That is a local MCP server, it runs over stdio, and Claude Code is the tool that supports it. Cowork does not: officially it takes hosted connectors only, which is why this particular job pushes you into the terminal whether you wanted to be there or not.

Checkpoint: you can say "Cloud" or "self-hosted" out loud with confidence. If it is Cloud, stop reading and use the official Atlassian server, it will take you ten minutes. Everything below is for self-hosted.

Step 2: Get five answers from IT before you install anything

Two of the pieces in this build are not technical decisions at all, and I have lost session time discovering that at the point where an install failed rather than the week before. Send this to whoever owns the machine and the Atlassian instance, then go and do something else.

1. Am I allowed to create a Personal Access Token in Jira and in Confluence?
2. Can I run Docker Desktop, or Python with uv, on this laptop?
3. Does our network route through an HTTP proxy I need to configure?
4. Do Jira and Confluence use a public certificate or an internal self-signed one?
5. Is security willing to approve a local open source connector that holds a
   read-only token to our Jira and Confluence, running on my machine?

Every blocker I have hit on this build is in that list, and all five are cheaper to discover by email than at minute forty of a working session. Question five is the one people skip and the one most likely to come back as a no. It is a fair question for a security team to ask, because the answer involves a third-party tool holding a credential to internal systems.

Checkpoint: you have a yes or a no against all five. A "no" on two or three is survivable. A "no" on one or five stops the build.

Step 3: Create a Personal Access Token in each product

Self-hosted Atlassian authenticates with Personal Access Tokens. This is not the same as the email-plus-API-token pair that Cloud uses, and mixing them up is the second most common reason this fails silently. If a guide tells you to set a username and an API token, that guide is about Cloud.

In Jira: your profile menu, then Personal Access Tokens, then Create token. Give it a name that says what it is for, set an expiry, copy it once because you will not see it again. Then do exactly the same thing in Confluence. They are separate products with separate tokens, even when they share a login.

Worth being clear about what you have just made. The token carries your own permissions, nothing more and nothing less. Anything Claude can do through it is something you could already do by hand, which is both the reassurance and the reason to keep it somewhere sensible.

Checkpoint: two tokens, saved in a password manager or a file you control, and not pasted into any chat window.

Step 4: Put the tokens in a file, not in your shell history

Create a .env.local file in a directory you own. This is what goes in it:

JIRA_URL=https://jira.internal.example.com
JIRA_PERSONAL_TOKEN=your_jira_pat
JIRA_SSL_VERIFY=true
CONFLUENCE_URL=https://confluence.internal.example.com
CONFLUENCE_PERSONAL_TOKEN=your_confluence_pat
CONFLUENCE_SSL_VERIFY=true
READ_ONLY_MODE=true

Then keep it out of version control before you forget, with echo ".env.local" >> .gitignore in the same directory.

Two of those lines are doing real work. READ_ONLY_MODE=true means the server exposes reading and searching but cannot create or edit anything, which is exactly what you want for a first run against a production instance. Leave the two SSL_VERIFY lines at true unless IT told you in step 2 that the certificate is internal and self-signed.

A token in an environment file is a real credential. If you are in the habit of pasting configuration into a chat window to ask what a line does, this is the moment to break it, and it is one of the ways people leak credentials with AI tools without ever doing anything they would call careless.

Checkpoint: git status does not list .env.local, and the file has real values in it rather than placeholders.

Step 5: Register the server with Claude Code

The server you want is the community mcp-atlassian project, which supports Cloud and Server or Data Center, and authenticates to self-hosted instances with the Personal Access Tokens you just made. There is also a Data Center focused fork if you want a second set of eyes on the same code. This is the piece your security team is being asked to approve in question five, so read the repository before you run it.

Two ways to register it. Pick whichever your machine allows.

Docker, which is how the project recommends running it:

claude mcp add atlassian -- docker run -i --rm --env-file .env.local ghcr.io/sooperset/mcp-atlassian:latest

Or Python through uvx, if Docker is not an option and you have uv installed:

claude mcp add atlassian \
  -e JIRA_URL=https://jira.internal.example.com \
  -e JIRA_PERSONAL_TOKEN=your_jira_pat \
  -e CONFLUENCE_URL=https://confluence.internal.example.com \
  -e CONFLUENCE_PERSONAL_TOKEN=your_confluence_pat \
  -e READ_ONLY_MODE=true \
  -- uvx mcp-atlassian

Note the -- in both commands. Everything after it is the command Claude Code will run to start the server, as a process on your machine, using your machine's network. That is the entire mechanism, and it is worth sitting with for a second: the reason this reaches a host that Anthropic's cloud cannot is that it is not Anthropic's cloud doing the reaching. If the protocol underneath this is new to you, what MCP actually is is the twenty-minute version.

The Docker route keeps your token in one gitignored file. The uvx route puts it in the command you just typed, which means it lands in your shell history and in your Claude Code configuration. Prefer Docker where you have the choice, and if you do not, at least know that the token is now sitting in two more places than you intended.

Checkpoint: the command returns without an error, and claude mcp list shows atlassian.

Step 6: Verify read-only, before you trust it with anything

Start Claude Code and check the connection from inside it rather than assuming:

claude
/mcp

You are looking for atlassian in that list, marked connected. If it is listed but failing, the error text there is the most useful diagnostic you will get, and it usually names the real problem: a hostname that does not resolve, a certificate it refuses, or a 401 from a token that was not accepted.

Once it shows connected, test with the smallest possible read requests, in plain English:

List the Jira projects I have access to.
Show me the five most recently updated pages in Confluence.

If real project keys and real page titles come back, you are done. That is the connection working, against your own instance, from your own machine.

Do not skip this and do not substitute asking Claude whether the connection worked. It will tell you something agreeable either way. /mcp reads the actual state, and a request that returns your real data is proof. Everything else is a guess with confidence attached.

Checkpoint: you are looking at project keys and page titles you recognise.

Step 7: Scope it down, then decide about writes

A working connection is not a finished setup. By default the server can see everything your account can see, which on a mature instance is usually far more than the two projects you actually work in. Narrow it, then consider writes:

JIRA_PROJECTS_FILTER=OPS,SUPPORT
CONFLUENCE_SPACES_FILTER=TEAMDOCS
READ_ONLY_MODE=false

Add the filters first and confirm they hold, then turn off read-only in a separate change so you know which edit caused what. You will need to re-register the server for changes to take effect, which is claude mcp remove atlassian followed by the add command from step 5.

Then test exactly one write, deliberately, somewhere you would not mind undoing: a comment on a ticket you own, or a page in your personal space. Writing is where an integration goes from useful to consequential, and the first write should be one you chose rather than one that happened while you were asking for something else.

Checkpoint: one intentional comment or page exists in Jira or Confluence, you can point at it in the browser, and the filters mean Claude can no longer see the projects you excluded.

Where this breaks

You followed a Cloud guide and the connection looks fine. This is the big one, and it accounts for most of the time lost to this problem. Nearly every video and top-ranking post on connecting Claude to Jira assumes Cloud, because Cloud is the easy case and the demo looks good. If your pages 404 while the server reports connected, you are pointed at a cloud bridge that has no route to your instance. Nothing in the error will tell you that.

Your admin has Personal Access Tokens disabled. Some Data Center administrators turn them off, and if yours has, there is no clever way around it. Your route is to ask for them to be enabled for your account, with the reason written down, or to fall back to the manual path below.

Docker is not yours to install. On a locked-down laptop, Docker Desktop and Python both tend to need admin rights. The uvx route is usually the easier ask, because uv and Python are a smaller request than a container runtime. If both are refused, this build is not available to you on that machine, and pretending otherwise just wastes a week.

Your traffic goes through a corporate proxy. The server is a separate process and does not inherit your browser's proxy settings. Pass HTTP_PROXY, HTTPS_PROXY and NO_PROXY into its environment alongside the token variables. This shows up as a connection that times out rather than one that is refused, which is a useful tell.

The certificate is internal and self-signed. Setting the SSL_VERIFY variables to false will get you moving in ten seconds, and it is the wrong permanent answer on a machine holding a token to internal systems. Get the internal certificate added to the trust store properly, and treat the false as a diagnostic step rather than a configuration choice.

Security says no to a community server. This is a legitimate outcome, not a defeat, and it is worth planning for before you ask. The fallback is the manual round trip: you export or copy the Confluence page or the ticket data, Claude restructures or drafts it locally, you paste the result back. It loses the automation and keeps most of the value, and it needs nothing from IT at all. If your whole stack is locked down like this, what to do when your company blocks the AI tools covers the wider version of the same problem.

You expected this to build the service desk for you. Connecting is not configuring. Creating a service project, its queues, its request types and its routing rules is Jira administration, done inside Jira by someone with the permissions to do it. Claude can design it, draft every request type and write the documentation, and once connected it can read and populate what exists. It cannot click the admin screens. I wrote that boundary up separately in can Claude set up your Jira service desk, and it is the single most common mismatch between what people expect from this connection and what it gives them.

What to build next

With reads working, the obvious next move is a CLAUDE.md in the repository you work from, holding your project keys, your space keys, the naming conventions your team uses and the format your tickets are expected to follow. That turns vague requests into specific ones and stops you re-explaining your own conventions every session.

After that, point it at something repetitive: a weekly summary of what moved in a project, a first-draft page from a set of tickets, or an intake template built from the last thirty requests your team actually received. The connection is only interesting for what it lets you stop doing by hand.

If you want to build this with someone watching your screen while IT answers the awkward questions, that is literally what my sessions are. Book a free Discovery Call and bring the five questions from step 2 with whatever answers you have.

These tutorials come from the actual curriculum I teach 1-on-1. This one was written for a real locked-down enterprise environment, including the parts IT had to approve first.

Written by Michael Murr for AI Tutor Code: private 1-on-1 online tutoring for professionals learning Python, AI tools, Data Science, ML, and LLM engineering. 200+ students taught, 3,000+ hours delivered.