mcp-server-atlassian-jira
Provides tools to interact with Atlassian Jira, enabling management of issues, attachments, and search via JQL.
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., "@mcp-server-atlassian-jira list all issues assigned to me in project PROJ"
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.
mcp-server-atlassian-jira (UFC fork)
Private UFC fork of
aashari/mcp-server-atlassian-jira
(forked at upstream commit aab8b7f2, one commit past v3.3.0), carrying:
Binary response corruption fix - upstream's
fetchAtlassian()(src/utils/transport.util.ts) read every response body viaresponse.text(); for binary endpoints (attachment content, thumbnails, exports) that is a lossy, irreversible UTF-8 decode. Fixed: non-JSON/text/XML bodies are read viaarrayBuffer()and returned as{ __binary: true, contentType, byteLength, base64 }. Covered by regression tests insrc/utils/transport.util.test.ts.Ported upstream community PR #173 (author
cedral) -jira_attach(multipart upload) andjira_get_attachment(byte-exact download to a local file).DOTENV_CONFIG_PATHwith~-expansion insrc/utils/config.util.ts@loadFromEnvFile, plusUSE_DOTENVtoggle - credentials live in a per-user file outside any repo/package tree (team convention:~/.claude/jira.env).Unconditional
main()insrc/index.ts(the upstreamrequire.main === moduleguard broke startup under embedded Node runtimes).node:httpstransport fallback (safeFetchinsrc/utils/transport.util.ts) - in some MCP host processes the globalfetch(undici) fails withTypeError: fetch faileddespite a live network (observed 2026-07-14 in a Claude-Code-session-spawned connector instance, while a Desktop-spawned instance on the same machine was fine). On that failure the request is retried through the classicnode:httpsstack (multipart encoded vianew Response(FormData), redirects followed withAuthorizationdropped cross-host).FORCE_HTTPS_FALLBACK=trueforces the fallback path (diagnostics / emergency lever). Verified live: JSON GET, JQL search, and a byte-exact 2.1 MB binary download through the media-CDN redirect.Unresolved-template env guard + creds-path fallback - some hosts pass the MCPB manifest env without substituting
${user_config.*}; a literal "${...}" value is non-empty and would shadow the .env file and leak into the URL ("ENOTFOUND ${user_config...}.atlassian.net"). Such values are now treated as unset, and when noDOTENV_CONFIG_PATHsurvives, the .env lookup falls back to<cwd>/.env, then~/.claude/jira.env.
Full background and verification evidence:
tools/jira-mcp-plugin/README.md in the 1C_Workspace repo.
How this repo is consumed
This repo exists as a standalone git package so that npx can install it
directly (npx cannot install from a monorepo subdirectory). The
jira@ufc-1c Claude Code plugin (marketplace arcankostenko/1C_Workspace)
declares:
"command": "npx",
"args": ["-y", "github:asky74/mcp-server-atlassian-jira#v3.3.0-ufc.3"]On first start npm clones this repo (using your system git - your existing
GitHub credentials cover the private access), installs devDependencies, and
the prepare script compiles TypeScript into dist/. Subsequent starts run
from the npx cache. No manual npm install step.
Releases are tags (v<upstream>-ufc.<n>, e.g. v3.3.0-ufc.1). To ship an
update: commit, tag, push the tag, then bump the tag in the plugin's
.mcp.json.
Local working-clone convention: 1C_Workspace/mcp-servers/mcp-server-atlassian-jira/
an inner repo like
BAS_KUP_local/(own.git/origin, not tracked by the monorepo's whitelist.gitignore).
Credentials: ~/.claude/jira.env with ATLASSIAN_SITE_NAME,
ATLASSIAN_USER_EMAIL, ATLASSIAN_API_TOKEN (see .env.example). Never
commit credentials here.
Related MCP server: Jira MCP Server
Development
npm install # also builds (prepare -> tsc)
npm test # 6 suites / 61 testsmanifest.json + .mcpbignore here build the optional Claude Desktop MCPB
bundle (npx @anthropic-ai/mcpb pack .) - a personal, per-machine option.
The 2026-07-13 "built-in-node fetch blocker" is not reproducible on
current Desktop (>=1.20186, Electron 42.5.1 / node 24.17): a probe script
run inside the real MCP runtime on 2026-07-14 got HTTP 200 from both undici
fetch and classic https.get, and the packed bundle works with the stock
command: "node" - no node.exe workaround needed. .mcpbignore caveat:
patterns are gitignore-style, keep them anchored (/src/, not src/) -
an unanchored src/ strips node_modules/*/src and breaks the bundle.
Licensing
Upstream declares "license": "ISC" in package.json but ships no LICENSE
file. This fork keeps the declared license and upstream attribution
(original work: Andi Ashari; attachment tools: cedral, PR #173).
Available Tools
7 toolsjira_attachJira Attach FileARead-only
Upload a file attachment to a Jira issue.
Two ways to attach files:
Local file: Provide
filePathto upload an existing filejira_attach({ issueIdOrKey: "PROJ-123", filePath: "/path/to/screenshot.png" })Text content: Provide
textContentandfileNameto create and upload a text filejira_attach({ issueIdOrKey: "PROJ-123", textContent: "Error log contents here...", fileName: "error.log" })
Supported file types: Images (png, jpg, gif), documents (pdf, doc, xls), text (txt, csv, json, md, log), archives (zip, tar), code files, and more.
Returns: Attachment metadata including ID, filename, size, and URL.
To list existing attachments: Use jira_get with:
path:
/rest/api/3/issue/{issueKey}jq:
fields.attachment[*].{id:id,filename:filename,size:size}
Inputs: issueIdOrKey (required), fileName, filePath, textContent.
jira_deleteJira DELETE RequestBRead-only
Delete Jira resources. Returns TOON format by default.
Output format: TOON (default) or JSON (outputFormat: "json")
Common operations:
Delete issue:
/rest/api/3/issue/{issueIdOrKey}Query param:deleteSubtasks=trueto delete subtasksDelete comment:
/rest/api/3/issue/{issueIdOrKey}/comment/{commentId}Delete worklog:
/rest/api/3/issue/{issueIdOrKey}/worklog/{worklogId}Delete attachment:
/rest/api/3/attachment/{attachmentId}Remove watcher:
/rest/api/3/issue/{issueIdOrKey}/watchersQuery param:accountId={accountId}
Note: Most DELETE endpoints return 204 No Content on success.
API reference: https://developer.atlassian.com/cloud/jira/platform/rest/v3/
Inputs: path (required), jq, queryParams, outputFormat.
jira_getJira GET RequestARead-only
Read any Jira data. Returns TOON format by default (30-60% fewer tokens than JSON).
IMPORTANT - Cost Optimization:
ALWAYS use
jqparam to filter response fields. Unfiltered responses are very expensive!Use
maxResultsquery param to restrict result count (e.g.,maxResults: "5")If unsure about available fields, first fetch ONE item with
maxResults: "1"and NO jq filter to explore the schema, then use jq in subsequent calls
Schema Discovery Pattern:
First call:
path: "/rest/api/3/search/jql", queryParams: {"maxResults": "1", "jql": "project=PROJ"}(no jq) - explore available fieldsThen use:
jq: "issues[*].{key: key, summary: fields.summary, status: fields.status.name}"- extract only what you need
Output format: TOON (default, token-efficient) or JSON (outputFormat: "json")
Common paths:
/rest/api/3/project- list all projects/rest/api/3/project/{projectKeyOrId}- get project details/rest/api/3/search/jql- search issues with JQL (usejqlquery param). NOTE:/rest/api/3/searchis deprecated!/rest/api/3/issue/{issueIdOrKey}- get issue details/rest/api/3/issue/{issueIdOrKey}/comment- list issue comments/rest/api/3/issue/{issueIdOrKey}/worklog- list issue worklogs/rest/api/3/issue/{issueIdOrKey}/transitions- get available transitions/rest/api/3/user/search- search users (usequeryparam)/rest/api/3/status- list all statuses/rest/api/3/issuetype- list issue types/rest/api/3/priority- list priorities
JQ examples: issues[*].key, issues[0], issues[*].{key: key, summary: fields.summary}
Example JQL queries: project=PROJ, assignee=currentUser(), status="In Progress", created >= -7d
API reference: https://developer.atlassian.com/cloud/jira/platform/rest/v3/
Inputs: path (required), jq, queryParams, outputFormat.
jira_get_attachmentJira Get AttachmentARead-only
Download a Jira attachment to a local file.
Usage:
jira_get_attachment({
attachmentId: "12345",
outputPath: "/tmp/report.pdf" // optional
})Parameters:
attachmentId(required): The attachment ID from issue metadataoutputPath(optional): Where to save the file. If not provided, saves to system temp directory with original filename.
To find attachment IDs: Use jira_get with:
path:
/rest/api/3/issue/{issueKey}jq:
fields.attachment[*].{id:id,filename:filename,size:size}
Returns: Download result with file path, filename, MIME type, and size.
Inputs: attachmentId (required), outputPath.
jira_patchJira PATCH RequestARead-only
Partially update Jira resources. Returns TOON format by default.
IMPORTANT - Cost Optimization: Use jq param to filter response fields.
Output format: TOON (default) or JSON (outputFormat: "json")
Common operations:
Update issue fields:
/rest/api/3/issue/{issueIdOrKey}body:{"fields": {"summary": "Updated title"}}(only updates specified fields)Update comment:
/rest/api/3/issue/{issueIdOrKey}/comment/{commentId}body:{"body": {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Updated comment"}]}]}}Update worklog:
/rest/api/3/issue/{issueIdOrKey}/worklog/{worklogId}body:{"timeSpentSeconds": 7200}
Note: PATCH only updates the fields you specify, leaving others unchanged.
API reference: https://developer.atlassian.com/cloud/jira/platform/rest/v3/
Inputs: body (required), path (required), jq, queryParams, +1 more.
jira_postJira POST RequestARead-only
Create Jira resources. Returns TOON format by default (token-efficient).
IMPORTANT - Cost Optimization:
Use
jqparam to extract only needed fields from response (e.g.,jq: "{key: key, id: id}")Unfiltered responses include all metadata and are expensive!
Output format: TOON (default) or JSON (outputFormat: "json")
Common operations:
Create issue:
/rest/api/3/issuebody:{"fields": {"project": {"key": "PROJ"}, "summary": "Issue title", "issuetype": {"name": "Task"}, "description": {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Description"}]}]}}}Add comment:
/rest/api/3/issue/{issueIdOrKey}/commentbody:{"body": {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Comment text"}]}]}}Add worklog:
/rest/api/3/issue/{issueIdOrKey}/worklogbody:{"timeSpentSeconds": 3600, "comment": {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Work done"}]}]}}Transition issue:
/rest/api/3/issue/{issueIdOrKey}/transitionsbody:{"transition": {"id": "31"}}Add attachment:
/rest/api/3/issue/{issueIdOrKey}/attachmentsNote: Requires multipart form data (complex - use Jira UI for attachments)
API reference: https://developer.atlassian.com/cloud/jira/platform/rest/v3/
Inputs: body (required), path (required), jq, queryParams, +1 more.
jira_putJira PUT RequestARead-only
Replace Jira resources (full update). Returns TOON format by default.
IMPORTANT - Cost Optimization: Use jq param to extract only needed fields from response
Output format: TOON (default) or JSON (outputFormat: "json")
Common operations:
Update issue (full):
/rest/api/3/issue/{issueIdOrKey}body:{"fields": {"summary": "New title", "description": {...}, "assignee": {"accountId": "..."}}}Update project:
/rest/api/3/project/{projectIdOrKey}body:{"name": "New Project Name", "description": "Updated description"}Set issue property:
/rest/api/3/issue/{issueIdOrKey}/properties/{propertyKey}body:{"value": "property value"}
Note: PUT replaces the entire resource. For partial updates, prefer PATCH.
API reference: https://developer.atlassian.com/cloud/jira/platform/rest/v3/
Inputs: body (required), path (required), jq, queryParams, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool maps to a distinct HTTP verb or operation (e.g., attach, delete, get, patch, post, put) with clear boundaries. Even jira_get_attachment (download) is separate from jira_get (read data) and jira_attach (upload).
All tools follow the 'jira_' prefix with an HTTP-method-like verb (attach, delete, get, get_attachment, patch, post, put). The naming is consistent, predictable, and clearly indicates the action.
With 7 tools covering core CRUD, file attachment, and flexible generic operations, the count is well-scoped for a Jira server. It provides sufficient functionality without unnecessary bloat.
The tool set covers all major CRUD operations and file attachments. While jira_get handles searches and listings, a dedicated search tool could improve completeness, but the current surface is largely complete for common Jira workflows.
Maintenance
Related MCP Connectors
Remote MCP server to run your Atako AI agents: chat, projects, files, integrations and channels.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
An MCP server that integrates with Discord to provide AI-powered features.
MCP Server for JFrog, providing tools for development and artifact management.
Related MCP Servers
- AlicenseCqualityDmaintenanceAn MCP server that enables communication with Jira, allowing users to perform operations like getting, searching, creating, and editing issues through natural language interaction.1MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server for integrating with Jira Server instances, enabling natural language interactions to create, update, search, and manage issues and comments.1MIT
- AlicenseNot gradedqualityDmaintenanceA comprehensive MCP server for Atlassian Jira that enables AI assistants to manage issues, sprints, comments, and worklogs through natural language.MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for interacting with Jira Cloud instances. Enables issue management, JQL queries, project and sprint management, and batch operations via natural language interfaces.141 npm4MIT