jira-mcp
Summary: This server provides read-only Jira access for issue investigation, relationship mapping, search, and image attachment retrieval.
Fetch full Jira issue details, including custom fields, attachment list, and optionally comments.
Retrieve an issue's comment thread with limit and newest-first controls.
Map an issue's context: parent, subtasks, linked issues, and epic children.
Run JQL searches and return compact issue results.
Download image attachments (png/jpeg/gif/webp, up to 5 MB) for visual analysis.
Identify the authenticated Atlassian account and selected base URL via
whoami.No write/create/update/delete/comment/transition tools are exposed in this schema.
Provides read-only access to Jira, enabling retrieval of issue details, comments, issue context (parent, subtasks, linked issues, epic children), JQL search results, and account verification.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@jira-mcp get issue PROJ-123 with comments"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
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 raisesReadOnlyViolationError, so a future edit that adds a write call fails loudly.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 |
| Full ticket detail including all non-empty custom fields (acceptance criteria, story points, ...) with their display names, plus (by default) the comment thread |
| Just the discussion, with author/timestamp/edited/visibility |
| Parent, subtasks, linked issues (with link direction), epic children, and remote links. Linked Confluence pages are shown with their page ID, ready for |
| Compact JQL search results |
| What a user did between two dates ( |
| Downloads an attachment (listed by |
Confluence
Tool | Purpose |
| 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 |
| 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 |
| Where the page sits in the tree: ancestors (top-level first) and direct children, each with title + ID |
| Plain words run a full-text search over pages and blog posts; anything with CQL syntax ( |
| Downloads an attachment of a page or comment ( |
Both
Tool | Purpose |
| 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, elseATLASSIAN_API_TOKEN), which then needswrite:jira-work(an unscoped token has it). Set a separate token withread:jira-work,write:jira-workandread:jira-userto 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 |
| Change only the passed fields. |
| Create an issue, returns the key |
| Comment IDs show as |
| Move to a status; the error lists the possible ones |
| e.g. |
| Link IDs show as |
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):
Only the routes in
WRITE_ROUTESare allowed. Nothing can be deleted except an issue link; issues, comments and attachments can't.Every write is checked against
JIRA_WRITE_PROJECTS, including the project in a create and both issues of a link.The read client (
JiraClient) is unchanged and still blocks every write. Confluence stays read-only.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) |
| Atlassian and this server |
One unscoped token (simplest) |
| 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:
Choose Create API token with scopes.
Select the Jira app and pick only these scopes:
read:jira-workread:jira-user
Copy the token immediately (it is shown only once) into
JIRA_API_TOKEN.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 bodiesread:comment:confluence: footer and inline commentsread:attachment:confluence: attachment lists and image downloadsread:space:confluence: space namesread:label:confluence: page labelsread:hierarchical-content:confluence: ancestors and childrenread:user:confluence: author names and the auth probesearch:confluence: CQL search (if search returns 403, also addread:content-details:confluence)
2. Configure .env
cp .env.example .env # then editThis is the whole configuration surface:
Key | Value |
| The email of your Atlassian account |
| e.g. |
| One unscoped token for both products (setup 2 in step 1) |
| A Jira-scoped token; wins over |
| A Confluence-scoped token; wins over |
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 syncOr with plain pip into a venv:
python -m venv .venv
.venv/bin/pip install -r requirements.txt # Windows: .venv\Scripts\pip4. 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 pageThis 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.netEach 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 acceptssite="<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
siteinstead 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 unlesssiteis given.get_user_activityreports every site, one section each, unlesssiteis 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
Interpreter: Settings → Project → Python Interpreter → Add Interpreter → Existing → select
.venv/bin/pythonin the project directory. (If you ranuv sync, the venv already exists with everything installed.)Run configuration for debugging: Run → Edit Configurations → + → Python:
Run: module
jira_mcp(choose "module" instead of "script path")Parameters:
--check PROJ-123Working 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_mcpWindows:
claude mcp add jira -- C:\path\to\PythonProject\.venv\Scripts\python.exe -m jira_mcpNotes:
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 projectto share via a checked-in.mcp.json, or--scope userto use it across all your projects.
Verify it's connected
Inside a Claude Code session:
Run
/mcp; thejiraserver 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 |
403 Forbidden | Scoped token missing |
Confluence 401/403 but Jira works | With scoped tokens, the Jira token cannot read Confluence. Create a Confluence-scoped token and set |
"No API token configured for ..." | That product has neither its own token variable nor |
"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 |
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 |
"short link" error for a Confluence URL |
|
Server won't start | Run |
Detection failed / anonymous responses | Startup logs (stderr) say which base URL was probed and why it was rejected. If |
Notes for developers new to Python
The venv (
.venv/) is a project-local copy of Python plus this project's packages: the equivalent ofnode_modules, except the interpreter itself lives inside it too. That's why Claude Code must be given.venv/bin/pythonby 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 viamcp.run(); the--checkmode 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_mcpruns the package's__main__.py, the closest thing Python has to an npmbinentry. It works from any directory becauseuv syncinstalled the project into the venv.
Available Tools
6 toolsget_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
Scored across 6 tools
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.
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.
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.
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
Connect to Atlassian Jira, Confluence, Loom, and more to search, create, and manage your work.
Manage dillie projects, tasks, and sprints; look up members and search platform documentation.
Search tickets, people, organizations and KB articles in Deskpro, and create tickets and replies.
Task manager your agent can fully operate: boards, tasks, sprints, roles, worklogs, day planner.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides read-only access to JIRA REST API, enabling LLMs to query and retrieve information from JIRA instances.149 npmMIT
- FlicenseNot gradedqualityDmaintenanceProvides read-only issue and project management tools for Jira Server/DC, enabling querying issues, projects, and assignments via natural language.-
- AlicenseAqualityDmaintenanceEnables interaction with Jira issues via JQL search, epic management, comments, attachments, and issue CRUD, with support for both Cloud and Server/Data Center instances.931 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables read-only interaction with JIRA instances via MCP, allowing searching issues, worklogs, sprints, users, and projects through natural language.MIT