Click on "Install 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-dev-mcp search for issues about user authentication"
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.
A local MCP server for Jira Cloud-driven development. Connects Claude Code, OpenCode, Codex, and other MCP clients to your Jira instance — search issues, read task details, parse attachments, and map Jira projects to local repositories.
Search Jira issues with natural language or raw JQL
Read full task details: description, subtasks, changelog, comments, attachments
Download and parse CSV, XLSX, XLS, PDF attachments via Python
Images and binary files passed to AI client as base64
Map Jira project keys to local repository paths
OAuth 2.0 (3LO) browser-based login — no manual token management
Auto-refresh OAuth tokens before expiry
Post comments on Jira issues with clickable URL response
Token-only comment confirmation: confirm pending comments with just the token, no need to re-send body
Edit existing comments with the same confirmation flow
Batch download all attachments from an issue in a single call with optional MIME filter
Auto-retry on transient API errors (429/503) with Retry-After header support
Rich ADF parsing: code blocks, tables, mentions, links, panels, and more
Multi-paragraph and fenced code block support in posted comments
Typed error hierarchy for programmatic error handling
OAuth callback port auto-fallback when default port is busy
Read and write Jira access
Related MCP server: Jira MCP Server
npm install -g jira-dev-mcpJust run:
jira-dev loginA browser window opens for Jira authorization. Tokens are saved to ~/.jira-dev/config.json and auto-refreshed. No manual Client ID or Secret required.
Advanced: To use your own OAuth app, set
JIRA_CLIENT_IDandJIRA_CLIENT_SECRETbefore runningjira-dev login.
export JIRA_BASE_URL="https://your-domain.atlassian.net"
export JIRA_EMAIL="you@example.com"
export JIRA_TOKEN="your-jira-api-token"Optional — store token in macOS Keychain instead of env var:
security add-generic-password -a "$USER" -s "jira-dev-mcp:JIRA_TOKEN" -w "your-token"jira-dev setupThis creates or updates ~/.claude.json (Claude Code) and ~/.opencode/config.json (OpenCode) automatically.
If an existing config file contains invalid JSON, jira-dev setup now fails with an explicit error instead of silently skipping it.
~/.claude.json){
"mcpServers": {
"jira": {
"command": "jira-dev",
"args": ["server"]
}
}
}{
"mcpServers": {
"jira": {
"command": "jira-dev",
"args": ["server"]
}
}
}{
"mcpServers": {
"jira": {
"command": "jira-mcp-server",
"env": {
"JIRA_BASE_URL": "https://your-domain.atlassian.net",
"JIRA_EMAIL": "you@example.com",
"JIRA_TOKEN": "your-token"
}
}
}
}Tool | Description |
| Search by keywords or JQL |
| Read full issue details |
| Download and parse a single attachment |
| Download all attachments in one call; optional MIME filter (e.g. |
| List issues assigned to you |
| Post a comment; confirm with token only (no body re-send needed) |
| Edit an existing comment; same token-only confirm flow |
| Map a Jira project to a local repo path |
| Get the local path for a project |
| Full investigation workflow: reads issue + comments + attachments, selects type-aware template (Bug/Story/Task), and guides step-by-step through explore → plan → implement → post comment |
jira-dev status # Show current auth mode, token state, and mapped projects
jira-dev doctor # Run environment and config health checks
jira-dev upgrade # Upgrade jira-dev-mcp from npm
jira-dev setup # Register jira-dev into supported MCP clients
jira-dev read AT-123 # Read issue details from the terminal
jira-dev comment AT-123 "Done" # Post a comment directly (bypasses manual mode)
jira-dev download AT-123 # Download all attachments
jira-dev download AT-123 spec.xlsx # Download a single attachment
jira-dev config set-comment-mode manual # Require confirmation before posting commentsStep 1 — One-time setup: map your project
jira_set_project_path(jiraProject: "AT", localPath: "/path/to/your/repo")Step 2 — Find your task
jira_my_tasks(status: "In Progress")or search by keyword / JQL:
jira_search_issues(query: "login timeout bug")
jira_search_issues(query: "project = AT AND sprint in openSprints()")Step 3 — Read the task
jira_read_task(key: "AT-123", includeComments: true)Returns: description, subtasks, changelog, comments, attachment list, and the local repo path.
Step 4 — Download attachments if needed
jira_download_all_attachments(key: "AT-123")
jira_download_all_attachments(key: "AT-123", mime_filter: "image/")
jira_download_attachment(key: "AT-123", filename: "spec.xlsx")Use jira_download_all_attachments to grab everything in one call, or filter by MIME type. Use jira_download_attachment for a single file. CSV / XLSX / XLS / PDF are parsed and returned as structured text. Images are returned as base64.
Step 5 — AI implements the fix
With the task details and local repo path in context, ask Claude Code to:
Explain the root cause
Propose a plan with impact scope
Implement the fix
Write test cases
Map a Jira project key to a local repo so the AI knows where to look:
jira_set_project_path(jiraProject: "AT", localPath: "/Users/you/projects/my-app")Python 3 is required for CSV, XLSX, XLS, and PDF parsing. For XLS and PDF, additional packages are auto-installed on first use, or install manually:
python3 -m pip install -r $(npm root -g)/jira-dev-mcp/scripts/requirements.txtOAuth tokens stored at ~/.jira-dev/config.json with 600 permissions
API tokens: prefer env vars or macOS Keychain over config file
Attachment size and MIME type allowlist enforced before download
OAuth client credentials injected at build time — never committed to source
Secrets are never written to logs
git clone https://github.com/nianyi778/jira-dev-mcp.git
cd jira-dev-mcp
npm install
npm run generate-defaults # required before first build (uses env vars or empty placeholders)
npm test
npm run buildInspect tools interactively:
npx @modelcontextprotocol/inspector node dist/index.jsMIT
Post a comment on a Jira issue. Returns the comment URL so you can verify it directly.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Jira issue key (e.g. AT-123). Required for new comments, optional when confirming with confirm_token. | |
| body | No | Comment text (plain text, will be wrapped in ADF paragraph). Required for new comments, optional when confirming with confirm_token. | |
| confirm_token | No | Confirmation token from preview step. When provided, key and body are optional — the pending comment content is used. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only mentions returning the comment URL, but omits important traits such as the need for authentication, the two-step confirmation flow (preview then confirm), and the fact that posting is a mutating action. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences. It front-loads the primary purpose and then provides a useful verification detail without any wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a non-trivial flow (optional confirmation token) that is not explained in the description. The description is too minimal to fully inform the agent about when to provide confirm_token or how the preview step works, making it incomplete for effective invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions already cover 100% of parameters with meaningful definitions (key, body, confirm_token), so the baseline is 3. The description adds no further parameter context, but it is not required given the schema's thoroughness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Post') and resource ('comment on a Jira issue'), and the distinction from sibling jira_edit_comment is evident. It also adds a concrete outcome (returns the comment URL), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to post a comment) but does not explicitly mention alternatives like jira_edit_comment for editing comments, nor does it explain the preview/confirm_token workflow. This leaves usage context somewhat implicit rather than fully guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full investigation and fix workflow for a Jira issue. Accepts an issue key (AT-123) or full browse URL. Reads the issue, prior comments, linked issues, and attachments; detects duplicate analysis (idempotency); selects a type-aware template (Bug/Story/Task); and provides step-by-step SOP: explore code → plan → baseline test → implement → build verify → post analysis comment. Use this instead of jira_read_task when you want to drive the full workflow end-to-end.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | Jira issue key (e.g. AT-123) or full browse URL (e.g. https://xxx.atlassian.net/browse/AT-123) | |
| auto_comment | No | Automatically post the completed analysis as a comment without asking for confirmation (default false, consistent with commentMode default of manual) | |
| response_format | No | Output format (default markdown) | |
| comment_max_results | No | Max comments to fetch for prior-analysis check (1-100, default 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses the tool's range of actions: reading issues/comments/attachments, idempotency detection, template selection, and a step-by-step SOP culminating in posting a comment. This provides substantial transparency about behavior, though it does not explicitly warn about side effects or output details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences, with a clear lead, a compact list of capabilities, and a specific usage directive. Every sentence adds distinct information; there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex with a multi-step workflow, and the description covers many aspects: accepted input, data sources, idempotency, template selection, and SOP steps. However, there is no output schema, and the description does not explicitly state what the tool returns beyond 'provides step-by-step SOP,' leaving the actual return value ambiguous. This gap prevents a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% parameter coverage with descriptions for all four params. The description only reiterates the input format (issue key or URL) in the same words, adding no extra semantic meaning. Therefore, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Full investigation and fix workflow for a Jira issue,' which clearly names the verb (analyze/fix) and resource (Jira issue). It further differentiates from the sibling by directing users to 'use this instead of jira_read_task when you want to drive the full workflow end-to-end,' making the tool's purpose distinct and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool over jira_read_task, providing a clear alternative. It also describes the workflow steps (explore → plan → implement → verify → comment), giving context on appropriate usage scenarios. No exclusion criteria are mentioned, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download all attachments from a Jira issue in a single call. Optionally filter by MIME type (e.g. "image/" for images only). Returns all files with their content inline. Use this instead of multiple jira_download_attachment calls.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Jira issue key (e.g. AT-123) | |
| mime_filter | No | Filter by MIME type prefix (e.g. "image/" for images only, "text/" for text files) | |
| response_format | No | Output format (default markdown) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that attachments are returned inline and that the operation is a single bulk call, plus the filtering behavior. It doesn't mention potential size limits or rate limits, but for a read-only download tool this is reasonable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with the core action, and each sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 params and no output schema, the description fully explains purpose, usage, and return behavior. It could mention edge cases like no attachments, but overall it's sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 3 parameters with descriptions, so baseline is 3. The description adds slightly by giving a concrete example for mime_filter and noting it's optional, but doesn't go beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Download') and resource ('all attachments from a Jira issue'), and clearly distinguishes itself from the sibling tool jira_download_attachment by stating it replaces multiple calls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool ('Use this instead of multiple jira_download_attachment calls') and mentions optional MIME type filtering, which covers the key usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download an attachment from a Jira issue. Text files (txt, md, json, log) are returned inline. CSV, XLS, XLSX, PDF are parsed by Python and returned as structured text. Images and other binary files are returned as base64.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Jira issue key (e.g. AT-123) | |
| filename | Yes | Attachment filename as listed in jira_read_task | |
| response_format | No | Output format (default json) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explains that text files (txt, md, json, log) are returned inline, CSV/XLS/XLSX/PDF are parsed into structured text, and images/binaries are returned as base64. This is significant added context, though it omits potential error responses or auth requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with no redundancy. The main action is front-loaded, and file-type handling follows logically. Every sentence adds meaningful information, making it highly scannable and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description compensates by explaining the main return format categories (inline, structured text, base64). It is incomplete regarding error handling and the exact JSON structure, but it covers the core behavior well for a download tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for all three parameters, giving 100% coverage. The description adds value by connecting attachment MIME types to output formats, but it does not clarify parameter semantics beyond schema, such as the meaning of response_format options or how to locate the filename.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Download an attachment from a Jira issue', specifying both the action (download) and the resource (attachment). It distinguishes from sibling tools like jira_download_all_attachments by focusing on a single attachment, and from jira_read_task by targeting attachment content rather than issue fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives like jira_download_all_attachments. It does not mention prerequisites (e.g., obtaining filename via jira_read_task) or exclusions, leaving usage entirely inferred from the tool name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit an existing Jira comment. In manual mode, returns a preview first and requires confirm_token to apply the update.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Jira issue key (e.g. AT-123). Required for new edits, optional when confirming with confirm_token. | |
| body | No | Updated comment text (plain text, will be wrapped in ADF paragraph). Required for new edits, optional when confirming with confirm_token. | |
| commentId | No | Existing Jira comment id. Required for new edits, optional when confirming with confirm_token. | |
| confirm_token | No | Confirmation token from preview step. When provided, key/commentId/body are optional — the pending content is used. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explicitly explains the two-step manual mode (preview first, then confirm_token to apply), which is a key behavioral trait. It could also mention error handling or what happens on invalid confirm_token, but the core behavior is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences that front-load the primary purpose and then concisely explain the manual mode. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with four well-documented parameters and no output schema, the description covers the essential context: what the tool does, the manual mode flow, and the role of confirm_token. No additional information is necessary for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with parameter descriptions, so the bar for added value is moderate. The description adds meaningful context by explaining the relationship between parameters: without confirm_token, it previews; with it, the update applies. This clarifies when each parameter is needed beyond the schema's standalone descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Edit') and resource ('existing Jira comment'), which distinguishes it from sibling tools like jira_add_comment. It also introduces the manual mode behavior, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it: for editing existing comments, as opposed to adding. It mentions manual mode with a preview and confirm_token, but does not explicitly state when not to use it or name alternative tools, leaving a small gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the local repository path mapped to a Jira project key.
| Name | Required | Description | Default |
|---|---|---|---|
| jiraProject | Yes | Jira project key (e.g. AT) | |
| response_format | No | Output format (default json) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action but does not explain what happens if no mapping exists, error behavior, or the output format. For a getter tool, this lack of context is a notable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundancy. It efficiently states the action and the resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should explain the return format or failure behavior but only states what the tool gets. The agent is left guessing about the response structure and error handling, which is critical for a lookup tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers both parameters with clear descriptions (e.g., 'Jira project key (e.g. AT)'), yielding 100% schema description coverage. The description adds no extra parameter detail, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('local repository path mapped to a Jira project key'), clearly distinguishing it from sibling tools like jira_set_project_path or jira_search_issues. It immediately conveys the exact function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (when you need the local repository path for a Jira project key) but does not explicitly state when not to use it or mention alternatives. No exclusion or comparison with sibling tools is provided, so guidance is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Jira issues assigned to the currently authenticated user, optionally filtered by status.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by status name (e.g. "In Progress", "To Do") | |
| startAt | No | Pagination offset (default 0) | |
| maxResults | No | Max results (1-50, default 10) | |
| response_format | No | Output format (default json) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden. It clearly indicates a read-only operation ('List') and scopes results to the authenticated user, implying safe usage. It does not mention pagination details or response format, but these are partially covered by the schema, so a 4 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence without any wasted words. It efficiently conveys the tool's purpose and the key optional filter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with no output schema, the description covers the core functionality and filter. It does not explicitly describe the response format, but the response_format parameter in the schema addresses that, so the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are fully described in the schema (100% coverage), so the description adds minimal parameter semantics beyond reinforcing the 'status' filter. The baseline of 3 applies because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'List' and specifies the resource as 'Jira issues assigned to the currently authenticated user', which is specific and clearly differentiates from sibling tools like jira_search_issues or jira_read_task. The optional status filter further clarifies the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states that the tool lists issues assigned to the current user, giving a solid context for when to use it. It does not explicitly mention alternatives or exclusions, so it falls short of a 5 due to lack of 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read raw details of a Jira issue (description, subtasks, changelog, labels, priority, parent, attachments). Data-only — does NOT guide analysis or post comments. Use jira_analyze_task when you need the full investigation workflow.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | Jira issue key or full browse URL (e.g. AT-123 or https://xxx.atlassian.net/browse/AT-123) | |
| commentStartAt | No | Comment pagination offset | |
| includeComments | No | Include comments (default false) | |
| response_format | No | Output format (default json) | |
| changelogStartAt | No | Changelog pagination offset | |
| commentMaxResults | No | Max comments (1-50, default 20) | |
| changelogMaxResults | No | Max changelog entries (1-100, default 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It clearly states this is a data-only read operation ('Read raw details', 'Data-only') and explicitly says it does not post comments or guide analysis, giving confidence that it has no side effects. However, it does not mention pagination behavior or any potential rate limits, which leaves minor gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: the first states exactly what the tool does, the second clarifies its scope limitations, and the third directs to the alternative workflow. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters and no output schema, the description provides a solid overview of its purpose, the data it returns, and its distinction from siblings. It does not explain default pagination values or error handling, but those are covered in the schema. It is complete enough for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a clear description (e.g., 'Comment pagination offset', 'Include comments (default false)'). The tool description adds a list of returned fields (description, subtasks, changelog, labels, priority, parent, attachments) which provides context, but does not add meaning to individual parameters beyond what the schema already offers. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read raw details') and a concrete resource ('a Jira issue'), enumerating the exact fields returned. It explicitly distinguishes itself from jira_analyze_task, noting it does NOT guide analysis, which clearly separates it from a key sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the reader when to use this tool vs. an alternative: 'Use jira_analyze_task when you need the full investigation workflow.' It also provides exclusions ('does NOT guide analysis or post comments'), making the usage boundary clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Jira issues using natural language keywords or raw JQL. Returns issue keys, summaries, statuses, and assignees.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query (keywords or JQL) | |
| startAt | No | Pagination offset (default 0) | |
| maxResults | No | Max results to return (1-50, default 10) | |
| response_format | No | Output format (default json) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full transparency burden. It discloses the return fields (keys, summaries, statuses, assignees), which is helpful, but does not mention read-only nature, error handling, pagination behavior, or any side effects. This is adequate but leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, front-loaded with the action and resource, followed by return information. No filler or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters fully documented in the schema and no output schema. The description covers the main search behavior and return fields, which is sufficient for basic usage. It could mention pagination or output format handling, but the schema already provides these details, so the description is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds no additional parameter semantics beyond what the schema already provides; 'natural language keywords or raw JQL' duplicates the schema's query description. The other parameters (startAt, maxResults, response_format) are fully described in the schema and not expanded in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Search Jira issues using natural language keywords or raw JQL' with a specific verb and resource, and lists return fields (keys, summaries, statuses, assignees). This clearly distinguishes it from sibling tools like jira_read_task and jira_my_tasks, which focus on retrieving specific tasks rather than searching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool: for searching issues with keywords or JQL. It implies the agent should use this for flexible search scenarios. However, it does not explicitly mention alternatives or exclusions, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Map a Jira project key to a local repository path. This enables jira_read_task to include the local path hint for code exploration.
| Name | Required | Description | Default |
|---|---|---|---|
| localPath | Yes | Absolute local path to the project repository | |
| jiraProject | Yes | Jira project key (e.g. AT) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose a key downstream effect (enabling jira_read_task to include the path hint), but it does not state whether the mapping overwrites an existing one, whether it persists, or any authorization requirements. This is a reasonable but not fully transparent disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tightly written sentences. The first sentence states the core action, and the second explains the practical benefit for jira_read_task. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter setter with no output schema, the description covers the main action, the purpose, and a meaningful integration context. It does not describe the return value or explain behavior on repeated calls, but given the tool's low complexity, this is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both parameters have clear descriptions in the schema). The description's mention of 'Jira project key' and 'local repository path' mirrors the schema without adding new constraints, formats, or examples, so it meets the baseline for high schema coverage without adding extra semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Map' with clear resources ('Jira project key' and 'local repository path'), and the mention of enabling jira_read_task distinguishes it from the sibling jira_get_project_path. Purpose is immediately clear and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context by explaining when this tool is useful: before jira_read_task, to include a local path hint for code exploration. It does not explicitly state when not to use it or mention the inverse tool jira_get_project_path, but the situational guidance is strong enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.4.5jira_add_commentjira_analyze_taskjira_download_all_attachmentsjira_download_attachmentjira_edit_commentjira_get_project_pathjira_my_tasksjira_read_taskjira_search_issuesjira_set_project_pathScored across 10 tools
Every tool has a clearly distinct purpose. The closest pair, jira_read_task and jira_analyze_task, is explicitly disambiguated: one is data-only, the other is a full workflow. Downloading single vs all attachments is also clearly distinguished.
All tools follow a jira_verb_noun pattern except jira_my_tasks, which breaks the convention by using a possessive adjective instead of a verb. Otherwise, naming is highly consistent and predictable.
With 10 tools, the set is well-scoped for a Jira dev integration. Each tool satisfies a distinct need, from project path mapping to comments, search, attachments, and a comprehensive analysis workflow.
The tool surface covers core read, search, comment, attachment, and workflow-driven analysis. Minor gaps exist—no issue creation, status transition, or assignment modification—but these are outside the apparent focus on investigation and commenting.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A MCP server built for developers enabling Git based project management with project and personal…
MCP Server for JFrog, providing tools for development and artifact management.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
