Skip to main content
Glama
mcp-server-atlassian-jira

mcp-server-atlassian-jira

by asky74

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:

  1. Binary response corruption fix - upstream's fetchAtlassian() (src/utils/transport.util.ts) read every response body via response.text(); for binary endpoints (attachment content, thumbnails, exports) that is a lossy, irreversible UTF-8 decode. Fixed: non-JSON/text/XML bodies are read via arrayBuffer() and returned as { __binary: true, contentType, byteLength, base64 }. Covered by regression tests in src/utils/transport.util.test.ts.

  2. Ported upstream community PR #173 (author cedral) - jira_attach (multipart upload) and jira_get_attachment (byte-exact download to a local file).

  3. DOTENV_CONFIG_PATH with ~-expansion in src/utils/config.util.ts@loadFromEnvFile, plus USE_DOTENV toggle - credentials live in a per-user file outside any repo/package tree (team convention: ~/.claude/jira.env).

  4. Unconditional main() in src/index.ts (the upstream require.main === module guard broke startup under embedded Node runtimes).

  5. node:https transport fallback (safeFetch in src/utils/transport.util.ts) - in some MCP host processes the global fetch (undici) fails with TypeError: fetch failed despite 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 classic node:https stack (multipart encoded via new Response(FormData), redirects followed with Authorization dropped cross-host). FORCE_HTTPS_FALLBACK=true forces 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.

  6. 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 no DOTENV_CONFIG_PATH survives, 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 tests

manifest.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 tools
jira_attachJira Attach FileA
Read-only

Upload a file attachment to a Jira issue.

Two ways to attach files:

  1. Local file: Provide filePath to upload an existing file

    jira_attach({
      issueIdOrKey: "PROJ-123",
      filePath: "/path/to/screenshot.png"
    })
  2. Text content: Provide textContent and fileName to create and upload a text file

    jira_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 RequestB
Read-only

Delete Jira resources. Returns TOON format by default.

Output format: TOON (default) or JSON (outputFormat: "json")

Common operations:

  1. Delete issue: /rest/api/3/issue/{issueIdOrKey} Query param: deleteSubtasks=true to delete subtasks

  2. Delete comment: /rest/api/3/issue/{issueIdOrKey}/comment/{commentId}

  3. Delete worklog: /rest/api/3/issue/{issueIdOrKey}/worklog/{worklogId}

  4. Delete attachment: /rest/api/3/attachment/{attachmentId}

  5. Remove watcher: /rest/api/3/issue/{issueIdOrKey}/watchers Query 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 RequestA
Read-only

Read any Jira data. Returns TOON format by default (30-60% fewer tokens than JSON).

IMPORTANT - Cost Optimization:

  • ALWAYS use jq param to filter response fields. Unfiltered responses are very expensive!

  • Use maxResults query 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:

  1. First call: path: "/rest/api/3/search/jql", queryParams: {"maxResults": "1", "jql": "project=PROJ"} (no jq) - explore available fields

  2. Then 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 (use jql query param). NOTE: /rest/api/3/search is 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 (use query param)

  • /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 AttachmentA
Read-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 metadata

  • outputPath (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 RequestA
Read-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:

  1. Update issue fields: /rest/api/3/issue/{issueIdOrKey} body: {"fields": {"summary": "Updated title"}} (only updates specified fields)

  2. Update comment: /rest/api/3/issue/{issueIdOrKey}/comment/{commentId} body: {"body": {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Updated comment"}]}]}}

  3. 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 RequestA
Read-only

Create Jira resources. Returns TOON format by default (token-efficient).

IMPORTANT - Cost Optimization:

  • Use jq param 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:

  1. Create issue: /rest/api/3/issue body: {"fields": {"project": {"key": "PROJ"}, "summary": "Issue title", "issuetype": {"name": "Task"}, "description": {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Description"}]}]}}}

  2. Add comment: /rest/api/3/issue/{issueIdOrKey}/comment body: {"body": {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Comment text"}]}]}}

  3. Add worklog: /rest/api/3/issue/{issueIdOrKey}/worklog body: {"timeSpentSeconds": 3600, "comment": {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "Work done"}]}]}}

  4. Transition issue: /rest/api/3/issue/{issueIdOrKey}/transitions body: {"transition": {"id": "31"}}

  5. Add attachment: /rest/api/3/issue/{issueIdOrKey}/attachments Note: 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 RequestA
Read-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:

  1. Update issue (full): /rest/api/3/issue/{issueIdOrKey} body: {"fields": {"summary": "New title", "description": {...}, "assignee": {"accountId": "..."}}}

  2. Update project: /rest/api/3/project/{projectIdOrKey} body: {"name": "New Project Name", "description": "Updated description"}

  3. 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

    A4/5.0

    Scored across 7 tools

    Disambiguation5/5

    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).

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for integrating with Jira Server instances, enabling natural language interactions to create, update, search, and manage issues and comments.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for interacting with Jira Cloud instances. Enables issue management, JQL queries, project and sprint management, and batch operations via natural language interfaces.
      141 npm
      4
      MIT