Skip to content
Back to search

jira-mcp

A Go-based MCP (Model Control Protocol) connector for Jira that enables AI assistants like Claude to interact with Atlassian Jira. This tool provides a seamless interface for AI models to perform common Jira operations including issue management, sprint planning, and workflow transitions.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nguyenvanduocit--jira-mcp/badge.svg)](/listings/nguyenvanduocit--jira-mcp)

HTML

<a href="/listings/nguyenvanduocit--jira-mcp"><img src="/api/listings/nguyenvanduocit--jira-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Copy this prompt to your AI assistant:

Install the Jira MCP server (https://github.com/nguyenvanduocit/jira-mcp) for my Claude Desktop or Cursor IDE. Read the MCP documentation carefully and guide me through the installation step by step.

If your AI assistant cannot help with this installation, it indicates either a misconfiguration or an ineffective AI tool. A capable AI assistant should be able to guide you through MCP installation.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 249 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ## Jira MCP
  2. An opinionated Jira MCP server built from years of real-world software development experience.
  3. Unlike generic Jira integrations, this MCP is crafted from the daily workflows of engineers and automation QC teams. You'll find sophisticated tools designed for actual development needs—like retrieving all pull requests linked to an issue, managing complex sprint transitions, or tracking development information across your entire workflow.
  4. This isn't just another API wrapper. It's a reflection of how professionals actually use Jira: managing sprints, tracking development work, coordinating releases, and maintaining visibility across teams. Every tool is designed to solve real problems that arise in modern software development.
  5. ## Available tools
  6. ### Issue Management
  7. - **jira_get_issue** - Retrieve detailed information about a specific issue including status, assignee, description, subtasks, and available transitions
  8. - **jira_create_issue** - Create a new issue with specified details (returns key, ID, and URL)
  9. - **jira_create_child_issue** - Create a child issue (sub-task) linked to a parent issue
  10. - **jira_update_issue** - Modify an existing issue's details (supports partial updates)
  11. - **jira_list_issue_types** - List all available issue types in a project with their IDs, names, and descriptions
  12. ### Search
  13. - **jira_search_issue** - Search for issues using JQL (Jira Query Language) with customizable fields and expand options
  14. ### Sprint Management
  15. - **jira_list_sprints** - List all active and future sprints for a specific board or project
  16. - **jira_get_sprint** - Retrieve detailed information about a specific sprint by its ID
  17. - **jira_get_active_sprint** - Get the currently active sprint for a given board or project
  18. - **jira_search_sprint_by_name** - Search for sprints by name with exact or partial matching
  19. ### Status & Transitions
  20. - **jira_list_statuses** - Retrieve all available issue status IDs and their names for a project
  21. - **jira_transition_issue** - Transition an issue through its workflow using a valid transition ID
  22. ### Comments
  23. - **jira_add_comment** - Add a comment to an issue (uses Atlassian Document Format)
  24. - **jira_get_comments** - Retrieve all comments from an issue
  25. ### Worklogs
  26. - **jira_add_worklog** - Add a worklog entry to track time spent on an issue
  27. ### History & Audit
  28. - **jira_get_issue_history** - Retrieve the complete change history of an issue
  29. ### Issue Relationships
  30. - **jira_get_related_issues** - Retrieve issues that have a relationship (blocks, is blocked by, relates to, etc.)
  31. - **jira_link_issues** - Create a link between two issues, defining their relationship
  32. ### Version Management
  33. - **jira_get_version** - Retrieve detailed information about a specific project version
  34. - **jira_list_project_versions** - List all versions in a project with their details
  35. ### Development Information
  36. - **jira_get_development_information** - Retrieve branches, pull requests, and commits linked to an issue via development tool integrations (GitHub, GitLab, Bitbucket)
  37. ## Installation
  38. Copy this prompt to your AI assistant:
  39. ```
  40. Install the Jira MCP server (https://github.com/nguyenvanduocit/jira-mcp) for my Claude Desktop or Cursor IDE. Read the MCP documentation carefully and guide me through the installation step by step.
  41. ```
  42. If your AI assistant cannot help with this installation, it indicates either a misconfiguration or an ineffective AI tool. A capable AI assistant should be able to guide you through MCP installation.
  43. ## CLI Usage
  44. In addition to the MCP server, `jira-mcp` ships a standalone CLI binary (`jira-cli`) for direct terminal use — no MCP client needed.
  45. ### Installation
  46. ```bash
  47. just install-cli
  48. # or
  49. go install github.com/nguyenvanduocit/jira-mcp/cmd/jira-cli@latest
  50. ```
  51. ### Quick Start
  52. ```bash
  53. export ATLASSIAN_HOST=your-instance.atlassian.net
  54. export ATLASSIAN_EMAIL=you@example.com
  55. export ATLASSIAN_TOKEN=your-api-token
  56. # or
  57. jira-cli --env .env <command> [flags]
  58. ```
  59. ### Commands
  60. | Command | Description |
  61. |---------|-------------|
  62. | `get-issue` | Get issue details |
  63. | `search-issues` | Search issues with JQL |
  64. | `create-issue` | Create a new issue |
  65. | `update-issue` | Update an existing issue |
  66. | `add-comment` | Add a comment to an issue |
  67. | `list-comments` | List comments on an issue |
  68. | `get-transitions` | Get available status transitions |
  69. | `transition-issue` | Transition issue to new status |
  70. | `list-sprints` | List sprints for a board |
  71. | `get-worklogs` | Get worklogs for an issue |
  72. | `add-worklog` | Log work on an issue |
  73. | `get-history` | Get issue change history |
  74. ### Examples
  75. ```bash
  76. # Get an issue
  77. jira-cli get-issue --issue-key PROJ-123
  78. # Search with JQL
  79. jira-cli search-issues --jql "project = PROJ AND status = 'In Progress'" --max-results 20
  80. # Create an issue
  81. jira-cli create-issue --project PROJ --summary "Fix login bug" --type Bug
  82. # Transition issue
  83. jira-cli get-transitions --issue-key PROJ-123
  84. jira-cli transition-issue --issue-key PROJ-123 --transition-id 31
  85. # JSON output
  86. jira-cli search-issues --jql "assignee = currentUser()" --output json | jq '.[].key'
  87. ```
  88. ### Flags
  89. Every command accepts:
  90. - `--env string` — Path to `.env` file
  91. - `--output string` — Output format: `text` (default) or `json`
  92. ## License
  93. MIT — see `LICENSE`.
  94. ## FOR AI
  95. > THIS SECTION IS FOR AI ONLY
  96. When working with this codebase, read these files to understand the project structure:
  97. 1. **CLAUDE.md** - Comprehensive project documentation including architecture, development commands, and coding conventions
  98. 2. **main.go** - Entry point that shows how the MCP server is initialized and tools are registered
  99. 3. **services/jira_client.go** - Singleton Jira client initialization and authentication
  100. 4. **tools/** - Individual tool implementations following consistent patterns
  101. 5. **docs/** - Detailed documentation (see structure below)
  102. Key concepts:
  103. - This is a Go-based MCP server that connects AI assistants to Jira
  104. - Each tool follows a registration + handler pattern with typed input validation
  105. - Tools are organized by category (issues, sprints, comments, worklogs, etc.)
  106. - All Jira operations use the `github.com/ctreminiom/go-atlassian` client library
  107. - Development principles documented in `.specify/memory/constitution.md`
  108. Before making changes, review:
  109. - **CLAUDE.md** for architecture patterns and development commands
  110. - **.specify/memory/constitution.md** for governance principles
  111. ## Quick start
  112. ### 1) Get an API token
  113. Create one at `https://id.atlassian.com/manage-profile/security/api-tokens`.
  114. ### 2) Add to Cursor
  115. Use Docker or a local binary (STDIO; no ports needed).
  116. #### Docker
  117. ```json
  118. {
  119. "mcpServers": {
  120. "jira": {
  121. "command": "docker",
  122. "args": [
  123. "run", "--rm", "-i",
  124. "-e", "ATLASSIAN_HOST=https://your-company.atlassian.net",
  125. "-e", "ATLASSIAN_EMAIL=your-email@company.com",
  126. "-e", "ATLASSIAN_TOKEN=your-api-token",
  127. "ghcr.io/nguyenvanduocit/jira-mcp:latest"
  128. ]
  129. }
  130. }
  131. }
  132. ```
  133. #### Binary
  134. ```json
  135. {
  136. "mcpServers": {
  137. "jira": {
  138. "command": "/usr/local/bin/jira-mcp",
  139. "env": {
  140. "ATLASSIAN_HOST": "https://your-company.atlassian.net",
  141. "ATLASSIAN_EMAIL": "your-email@company.com",
  142. "ATLASSIAN_TOKEN": "your-api-token"
  143. }
  144. }
  145. }
  146. }
  147. ```
  148. ### 3) Try it in Cursor
  149. - “Show my issues assigned to me”
  150. - “What’s in the current sprint for ABC?”
  151. - “Create a bug in ABC: Login fails on Safari”
  152. ## Configuration
  153. - **ATLASSIAN_HOST**: `https://your-company.atlassian.net`
  154. - **ATLASSIAN_EMAIL**: your Atlassian email
  155. - **ATLASSIAN_TOKEN**: API token
  156. Optional `.env` (if running locally):
  157. ```bash
  158. ATLASSIAN_HOST=https://your-company.atlassian.net
  159. ATLASSIAN_EMAIL=your-email@company.com
  160. ATLASSIAN_TOKEN=your-api-token
  161. ```
  162. HTTP mode (optional, for debugging):
  163. ```bash
  164. jira-mcp -env .env -http_port 3000
  165. ```
  166. Cursor config (HTTP mode):
  167. ```json
  168. { "mcpServers": { "jira": { "url": "http://localhost:3000/mcp" } } }
  169. ```
  170. ### Limiting which tools are exposed (ENABLED_TOOLS)
  171. By default every Jira tool is registered. To expose only a subset — for example, to hand an AI agent a read-only view of Jira — set the `ENABLED_TOOLS` environment variable to a comma-separated allowlist of tool names:
  172. ```bash
  173. ENABLED_TOOLS=jira_get_issue,jira_search_issue,jira_get_comments
  174. ```
  175. Rules:
  176. - Unset or empty → all tools are exposed (backwards compatible).
  177. - Whitespace around names is tolerated.
  178. - Unknown names are ignored but logged at startup so typos surface immediately.
  179. - Names that are not listed are simply not registered, so the MCP client never sees them.
  180. Read-only agent example (exposes 15 reads, blocks all 8 mutating tools):
  181. ```bash
  182. ENABLED_TOOLS=jira_get_issue,jira_search_issue,jira_list_statuses,jira_get_comments,jira_get_issue_history,jira_get_related_issues,jira_list_sprints,jira_get_sprint,jira_get_active_sprint,jira_search_sprint_by_name,jira_get_version,jira_list_project_versions,jira_get_development_information,jira_download_attachment,jira_list_issue_types
  183. ```
  184. ## Installation
  185. ### Homebrew (macOS/Linux)
  186. ```bash
  187. brew install nguyenvanduocit/tap/jira-mcp
  188. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.