Skip to main content
Glama

Jira & Confluence MCP Server (read-only, optional Jira writes)

A local MCP server that lets Claude Code pull Jira ticket context (issue details, comment threads, the reference graph around a ticket, and JQL search results) and Confluence content (pages, blog posts, footer and inline comments, the page tree, and CQL search results), all rendered as compact Markdown. Image attachments from either product (the screenshot on a UI bug ticket, a diagram in a spec page) can be fetched for Claude to analyze visually, and text attachments (logs, stack traces, JSON/HAR, CSV, source code, ...) come back as plain text.

What it deliberately cannot do

By default this server is strictly read-only (Jira writes are an opt-in, see "Optional: Jira writes"; Confluence is always read-only). It exposes no tool that creates, updates, transitions, deletes, or comments on anything. Enforcement is layered:

  1. In code: every HTTP request (Jira and Confluence) funnels through a single helper that only permits GET, with one allowlisted exception: POST /rest/api/3/search/jql, a read operation that Atlassian requires be sent as POST. Confluence has no POST exception at all. Any other method raises ReadOnlyViolationError, so a future edit that adds a write call fails loudly.

  2. At the credential level: create the API token with only read scopes (below), so even a bug could not write.

Related MCP server: Jira MCP Server

Tools

Jira

Tool

Purpose

get_issue(issue_key, include_comments=True)

Full ticket detail including all non-empty custom fields (acceptance criteria, story points, ...) with their display names, plus (by default) the comment thread

get_comments(issue_key, limit=100, newest_first=False)

Just the discussion, with author/timestamp/edited/visibility

get_issue_context(issue_key)

Parent, subtasks, linked issues (with link direction), epic children, and remote links. Linked Confluence pages are shown with their page ID, ready for get_confluence_page

search_issues(jql, limit=25)

Compact JQL search results

get_user_activity(from_date, to_date, user="me", include_confluence=False, max_issues=50)

What a user did between two dates (yyyy-MM-dd, to_date exclusive): their comments (with mentions), status transitions, field edits and issue creations, grouped by issue and as one timeline, in the authenticated user's timezone. user is "me" or an accountId. Finds issues via updatedBy(accountId, from, to) JQL, then reads each issue's changelog and comments (5 in parallel). With include_confluence, also lists Confluence pages the user contributed to that were last modified in the range. Truncation and per-issue failures are reported in the output instead of failing the call

get_attachment(attachment_id)

Downloads an attachment (listed by get_issue). Images (png/jpeg/gif/webp) come back as vision input, so Claude can look at screenshots; text files (detected by mime type, or by extension when Jira reports application/octet-stream) come back as text. Files of unknown type and extension (e.g. Dockerfile, app.log.1) are downloaded and served as text if their content has no NUL bytes and is valid UTF-8 (or UTF-16 with BOM). Text over 20,000 characters is saved in full (as UTF-8) under <tmp>/jira-mcp/attachments/, and the tool returns that path plus the first and last 50 lines, so Claude can grep or page through the file instead of loading it all. Max 5 MB; videos, PDFs, archives and other binary files are rejected

Confluence

Tool

Purpose

get_confluence_page(page, include_comments=True)

A page or blog post (by numeric ID or URL): space, version, author/owner, labels, URL, the full body (tables, task lists, macros; embedded Jira issues shown as [Jira issue: KEY]; embedded images labelled with their attachment ID), the attachment list, and (by default) all footer + inline comments with reply threads

get_confluence_comments(page, limit=100, newest_first=False)

Just the discussion: footer comments, then inline comments (quoting the highlighted text, marked if resolved), replies nested. Images pasted into comments are labelled with their attachment ID

get_confluence_page_context(page)

Where the page sits in the tree: ancestors (top-level first) and direct children, each with title + ID

search_confluence(query, limit=25)

Plain words run a full-text search over pages and blog posts; anything with CQL syntax (space = ENG AND title ~ "auth") is sent as CQL

get_confluence_attachment(attachment_id)

Downloads an attachment of a page or comment (att… ID from get_confluence_page/get_confluence_comments). Same behavior as get_attachment: images as vision input, text files as text (long ones saved to a file with a preview), max 5 MB. Passing a page ID or URL by mistake returns that page's readable attachment IDs

Both

Tool

Purpose

whoami()

Which account each product's token resolves to, per configured site (Jira and Confluence reported separately), and which environment variable each token came from; the first stop for auth debugging

Every tool except whoami also takes an optional site argument; see Multiple sites.

Optional: Jira writes

Off by default. To turn them on, set in .env:

  • JIRA_WRITE_PROJECTS: comma-separated project keys the write tools may touch, e.g. AC. Required.

  • JIRA_WRITE_API_TOKEN: optional. Without it the writes use the Jira token (JIRA_API_TOKEN, else ATLASSIAN_API_TOKEN), which then needs write:jira-work (an unscoped token has it). Set a separate token with read:jira-work, write:jira-work and read:jira-user to keep the read token read-only.

Then restart the MCP server (start a new Claude Code session). The startup log says "Jira writes enabled for projects: …".

Tool

Purpose

update_issue(issue_key, summary, description, assignee, labels, fields)

Change only the passed fields. fields takes display names or IDs, e.g. {"Acceptance Criteria": "...", "Epic Link": "AC-38"}. assignee="none" unassigns

create_issue(project, summary, description, issue_type, parent, assignee, fields)

Create an issue, returns the key

add_comment(issue_key, body) / edit_comment(issue_key, comment_id, body)

Comment IDs show as (comment 12345) in get_issue

transition_issue(issue_key, status)

Move to a status; the error lists the possible ones

link_issues(issue_key, relation, other_key)

e.g. ("AC-66", "is blocked by", "AC-14"); the link is read back to check its direction

unlink_issues(link_id)

Link IDs show as (link 12345) in get_issue_context

Text is Jira wiki markup (REST v2), not Markdown.

With several sites configured, every write tool takes the same optional site argument as the read tools: issue keys and the project of create_issue are routed to the site that has the project, and unlink_issues needs site because a link ID does not identify a site. JIRA_WRITE_PROJECTS applies to every site.

Guard rails, all in JiraWriteClient (client.py):

  1. Only the routes in WRITE_ROUTES are allowed. Nothing can be deleted except an issue link; issues, comments and attachments can't.

  2. Every write is checked against JIRA_WRITE_PROJECTS, including the project in a create and both issues of a link.

  3. The read client (JiraClient) is unchanged and still blocks every write. Confluence stays read-only.

  4. Claude Code asks before each tool call unless you allow the tool in your permissions.

Setup

1. Create Atlassian API tokens

Tokens are created at https://id.atlassian.com/manage-profile/security/api-tokens and belong to your account, so the same tokens work for every site you configure. Pick one of two setups:

Setup

Variables

Read-only enforced by

Scoped tokens (recommended)

JIRA_API_TOKEN and/or CONFLUENCE_API_TOKEN

Atlassian and this server

One unscoped token (simplest)

ATLASSIAN_API_TOKEN

this server only

A scoped token is bound to one app, which is why the scoped setup needs one token per product. Setting only one of the two is fine: the other product's tools then report that no token is configured.

Scoped tokens:

  1. Choose Create API token with scopes.

  2. Select the Jira app and pick only these scopes:

    • read:jira-work

    • read:jira-user

  3. Copy the token immediately (it is shown only once) into JIRA_API_TOKEN.

  4. For Confluence, repeat with the Confluence app and the scopes below, and put that token in CONFLUENCE_API_TOKEN.

One unscoped token: choose Create API token and put it in ATLASSIAN_API_TOKEN. It works for both products, but it can do everything your account can, so read-only then rests on this server's request guard alone.

Each product uses its own variable if set and falls back to ATLASSIAN_API_TOKEN otherwise. The server handles both token kinds automatically (see below).

Confluence token scopes

Select only read scopes:

  • read:page:confluence, read:blogpost:confluence: page and blog post bodies

  • read:comment:confluence: footer and inline comments

  • read:attachment:confluence: attachment lists and image downloads

  • read:space:confluence: space names

  • read:label:confluence: page labels

  • read:hierarchical-content:confluence: ancestors and children

  • read:user:confluence: author names and the auth probe

  • search:confluence: CQL search (if search returns 403, also add read:content-details:confluence)

2. Configure .env

cp .env.example .env   # then edit

This is the whole configuration surface:

Key

Value

ATLASSIAN_EMAIL

The email of your Atlassian account

ATLASSIAN_SITE_URL

e.g. https://your-company.atlassian.net (shared by Jira and Confluence). Several sites: separate them with commas; see Multiple sites

ATLASSIAN_API_TOKEN

One unscoped token for both products (setup 2 in step 1)

JIRA_API_TOKEN

A Jira-scoped token; wins over ATLASSIAN_API_TOKEN for Jira

CONFLUENCE_API_TOKEN

A Confluence-scoped token; wins over ATLASSIAN_API_TOKEN for Confluence

The email, the site URL and at least one token are required.

.env is gitignored; never commit it. Real environment variables take precedence over the file. The file is located relative to the project directory (not the working directory), so the server finds it no matter where it is launched from.

3. Install dependencies

With uv (preferred, since this repo has a uv.lock):

uv sync

Or with plain pip into a venv:

python -m venv .venv
.venv/bin/pip install -r requirements.txt   # Windows: .venv\Scripts\pip

4. Verify with --check

.venv/bin/python -m jira_mcp --check            # connectivity + auth only
.venv/bin/python -m jira_mcp --check PROJ-123   # also fetch a ticket in full
.venv/bin/python -m jira_mcp --check --page 123456   # also fetch a Confluence page

This prints whether .env was found, the configured sites, and for each site and product: which base URL was selected (and whether the cloud-ID fallback was needed), the authenticated account and the variable its token came from. When a key or page is given, it also prints the content exactly as Claude would see it. --page accepts a numeric page ID or a full page URL; with several sites, add --site NAME for a numeric page ID.

Multiple sites

If your account belongs to several Atlassian sites (orgs), list them all:

ATLASSIAN_SITE_URL=https://acme.atlassian.net,https://other-org.atlassian.net

Each site is named after its subdomain (acme, other-org; a custom domain keeps its full hostname) and the first one is the default. The same email and tokens are used for all of them. With more than one site configured:

  • Every result starts with a Site: line, and every tool accepts site="<name>".

  • Issue keys are routed automatically: the server checks which site has the key's project (one request per site, cached per project). If the project exists on several sites, or on none, the tool returns an error asking for site instead of guessing.

  • URLs (Confluence pages) are routed by their hostname.

  • Bare IDs (attachment IDs, numeric page IDs) are only unique within a site, so they require site.

  • Searches (search_issues, search_confluence) run on the default site unless site is given.

  • get_user_activity reports every site, one section each, unless site is given.

ATLASSIAN_CLOUD_ID identifies one site, so it cannot be combined with several.

Scoped vs. unscoped tokens: the base URL problem

  • An unscoped token works against your site URL, https://<site>.atlassian.net.

  • A scoped token against that same URL fails silently, returning anonymous-looking responses. It must call https://api.atlassian.com/ex/jira/{cloudId} (or /ex/confluence/{cloudId} for Confluence) instead.

You do not need to know which kind you hold. On first use the server probes the site URL with GET /rest/api/3/myself (Confluence: GET /wiki/rest/api/user/current); if that does not return a real account, it fetches your cloud ID from {site}/_edge/tenant_info and retries against api.atlassian.com. The winner is cached for the process lifetime and logged to stderr. Jira and Confluence are detected independently, so one can use an unscoped token and the other a scoped one.

If detection ever fails: _edge/tenant_info is not part of Atlassian's formally supported REST API (though Atlassian's own support docs point at it), so it could change. In that case set ATLASSIAN_CLOUD_ID in .env to skip detection; the error message will tell you when this applies. You almost never need it.

PyCharm setup

  1. Interpreter: Settings → Project → Python Interpreter → Add Interpreter → Existing → select .venv/bin/python in the project directory. (If you ran uv sync, the venv already exists with everything installed.)

  2. Run configuration for debugging: Run → Edit Configurations → + → Python:

    • Run: module jira_mcp (choose "module" instead of "script path")

    • Parameters: --check PROJ-123

    • Working directory: the project root (anything works, but this is tidy)

    Now you can set breakpoints anywhere (e.g. in client.py) and debug real requests. Errors inside a running MCP server are otherwise invisible.

Connect to Claude Code

Use the venv's Python by absolute path; a bare python won't resolve to the venv when Claude Code spawns the server.

macOS/Linux:

claude mcp add jira -- /path/to/PythonProject/.venv/bin/python -m jira_mcp

Windows:

claude mcp add jira -- C:\path\to\PythonProject\.venv\Scripts\python.exe -m jira_mcp

Notes:

  • Everything after -- is the command Claude runs; everything before it is Claude's own options.

  • Default scope is local (just you, just this project, stored in ~/.claude.json). Add --scope project to share via a checked-in .mcp.json, or --scope user to use it across all your projects.

Verify it's connected

Inside a Claude Code session:

  • Run /mcp; the jira server should be listed as connected, with twelve tools.

  • Or just ask: "use whoami to check the jira connection".

Troubleshooting

Symptom

Likely cause and fix

401 Unauthorized

Wrong email or token, or the token was revoked/expired. Recreate the token and update .env. Run --check to confirm.

403 Forbidden

Scoped token missing read:jira-work / read:jira-user, or your account lacks site access. Recreate the token with both read scopes.

Confluence 401/403 but Jira works

With scoped tokens, the Jira token cannot read Confluence. Create a Confluence-scoped token and set CONFLUENCE_API_TOKEN. whoami shows each product's status and token variable separately.

"No API token configured for ..."

That product has neither its own token variable nor ATLASSIAN_API_TOKEN. Set one of the two named in the error.

"exists on several sites" / "is an ID, which does not identify a site"

Several sites are configured and the input does not pin one down. Pass site (the name from whoami or from the Site: line of an earlier result).

404 Not Found

The issue or page doesn't exist, or your account lacks permission to see it. Jira reports issues you cannot view as 404, and a token never grants more access than the human it belongs to. Verify you can open the ticket in a browser while logged in as that account.

Empty tool list in Claude

The server crashed at startup. Run the exact command from claude mcp add yourself in a terminal; startup errors print to stderr. Usual causes: wrong Python path, or missing .env keys.

"short link" error for a Confluence URL

/wiki/x/… short links can't be resolved without a browser. Open the link and pass the full page URL (or the numeric ID from it).

Server won't start

Run --check. If it reports missing config, fix .env. If imports fail, re-run uv sync (or reinstall requirements.txt) and confirm the venv Python is ≥ 3.11.

Detection failed / anonymous responses

Startup logs (stderr) say which base URL was probed and why it was rejected. If _edge/tenant_info is unreachable, set ATLASSIAN_CLOUD_ID in .env.

Notes for developers new to Python

  • The venv (.venv/) is a project-local copy of Python plus this project's packages: the equivalent of node_modules, except the interpreter itself lives inside it too. That's why Claude Code must be given .venv/bin/python by absolute path: there's no global install to fall back on.

  • asyncio.run(...) is needed because async functions in Python don't run just by calling them; calling one returns a coroutine object, and something has to drive it. There's no ambient event loop like in Node; asyncio.run() creates a loop, runs one coroutine to completion, and tears the loop down. The MCP server does this internally via mcp.run(); the --check mode does it explicitly.

  • The decorators (@mcp.tool) are functions that receive the function defined below them and register/wrap it, like a middleware factory applied at definition time. FastMCP's decorator reads the function's name, type hints, and docstring to generate the MCP tool schema that Claude sees; the docstring is the tool's API documentation.

  • python -m jira_mcp runs the package's __main__.py, the closest thing Python has to an npm bin entry. It works from any directory because uv sync installed the project into the venv.

Available Tools

6 tools
get_attachmentA

Download an image attached to a Jira issue, for visual analysis.

Returns the image itself so it can be looked at directly. Use it when a ticket's Attachments section (from get_issue) lists a screenshot or other image relevant to the task, e.g. a UI bug report where the screenshot shows the actual broken state.

Only images are supported (png, jpeg, gif, webp) up to 5 MB; videos and other file types are rejected with an explanatory error.

Inputs: attachment_id (required).

get_commentsA

Get only the comment thread of a Jira issue, as Markdown.

Each comment includes author, timestamp, whether it was edited, and any visibility restriction. Use this instead of get_issue when the ticket body is already known and only the discussion is needed.

Inputs: issue_key (required), limit, newest_first. Returns: result

get_issueA

Get full detail for one Jira issue as Markdown.

Returns summary, status, type, priority, resolution, assignee, reporter, labels, components, fix versions, created/updated timestamps, the full description, all non-empty custom fields (e.g. acceptance criteria, story points) with their display names, the attachment list (fetch images via get_attachment), and (by default) the complete comment thread.

Inputs: issue_key (required), include_comments. Returns: result

get_issue_contextA

Map the reference graph around a Jira issue: parent, subtasks, links.

Returns the parent (e.g. epic), all subtasks, and all linked issues — each resolved to key + type + status + summary so the next issue to read can be chosen without further calls. Link relationships are given in human terms with correct direction ("blocks" vs "is blocked by"). For epics, also lists the issues inside the epic.

Inputs: issue_key (required). Returns: result

search_issuesA

Search Jira with a JQL query; returns a compact Markdown list.

Each result line has key, type, status, summary, assignee and last update. Example JQL: 'project = PROJ AND status != Done ORDER BY updated DESC'. Results are capped at limit (1-100); the output notes when more matches exist.

Inputs: jql (required), limit. Returns: result

whoamiA

Report which Atlassian account this server is authenticated as.

Returns display name, email, account ID, and which base URL was selected (site URL vs cloud-ID fallback). Call this first when any other tool returns authentication or permission errors — it isolates whether the problem is the credentials or the specific resource.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose: whoami validates identity, get_issue loads full details, get_comments retrieves only the discussion, get_issue_context maps relationships, search_issues runs JQL queries, and get_attachment downloads image content. No two tools overlap in function.

    Naming Consistency5/5

    All tools follow a consistent snake_case verb_noun pattern (get_issue, get_comments, search_issues, etc.). The only exception is 'whoami', which is a standard, recognizable command name and does not break the overall pattern.

    Tool Count5/5

    Six tools cover the essential read-only workflows for a Jira server: authentication, issue retrieval, comment access, relationship mapping, search, and attachment download. The count is well-scoped for the server's purpose without being excessive or sparse.

    Completeness4/5

    The surface covers common read-only Jira tasks comprehensively, including authentication, issue detail, comments, links, search, and images. Minor gaps exist—such as lacking project listing or issue creation/update—but these appear intentionally omitted for a read-centric server.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables interaction with Jira issues via JQL search, epic management, comments, attachments, and issue CRUD, with support for both Cloud and Server/Data Center instances.
      9
      31 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables read-only interaction with JIRA instances via MCP, allowing searching issues, worklogs, sprints, users, and projects through natural language.
      MIT