Jira MCP Server + Claude Code (2026)

Last updated: April 17, 2026

Project management automation becomes significantly more powerful when Claude Code connects directly to your Jira instance. The Jira MCP server enables Claude to interact with tickets, manage workflows, query issues, and automate repetitive project management tasks through natural language commands. This guide covers practical integration patterns for developers and power users who want to streamline their Jira workflows, with concrete configuration examples, JQL query patterns, and automation recipes you can use immediately.

Why Integrate Jira with Claude Code

If you spend significant time switching between your terminal and Jira’s web interface, the Jira MCP server eliminates that context switching. You can create issues, update status, search for tickets, and generate reports without leaving your development environment. The integration works particularly well when combined with other Claude skills like the tdd skill for test-driven development workflows or the pdf skill for generating project documentation.

The Model Context Protocol provides a standardized way for Claude to communicate with Jira’s REST API. This means you get type-safe interactions, automatic request handling, and consistent error responses, all through conversational commands. Rather than memorizing JQL syntax or navigating Jira’s multi-step issue creation forms, you describe what you want in plain language and the MCP server handles the API translation.

The Time Cost of Manual Jira Management

Consider a typical sprint kickoff without automation. A team of five developers each spending three minutes per ticket to update status, add comments, and link related issues across a thirty-ticket sprint consumes roughly forty-five minutes of collective time, time that repeats every sprint. Over a year of two-week sprints, that’s roughly nineteen hours per developer lost to administrative overhead. The Jira MCP integration targets exactly this category of repetitive, low-value work.

Prerequisites and Initial Setup

Before configuring the Jira MCP server, ensure you have Node.js 18 or later installed and a Jira API token. Generate your API token from your Atlassian account settings at id.atlassian.com. Navigate to Security > API tokens > Create API token. You’ll also need your Jira site URL (e.g., yourcompany.atlassian.net).

Install the Jira MCP server using npm:

npm install -g @modelcontextprotocol/server-jira

Configure the server by creating or updating your MCP settings file at ~/.claude/mcp-servers.json:

{
 "mcpServers": {
 "jira": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-jira"],
 "env": {
 "JIRA_HOST": "yourcompany.atlassian.net",
 "JIRA_EMAIL": "[email protected]",
 "JIRA_API_TOKEN": "your-api-token-here"
 }
 }
 }
}

Restart Claude Code after adding this configuration. The server automatically connects to your Jira instance and exposes available tools for project interaction. You can verify the connection is working by asking Claude:

“List the Jira projects I have access to.”

If the MCP server is connected, Claude returns a formatted list of project keys and names. If it fails, check the troubleshooting section at the end of this guide.

Verifying Available Tools

Once connected, Claude Code has access to a set of Jira tools via the MCP server. The core tools available include:

Tool	Description
`create_issue`	Create a new issue with type, summary, description, and fields
`get_issue`	Retrieve full details of a specific issue by key
`update_issue`	Modify fields on an existing issue
`search_issues`	Execute JQL queries and return matching issues
`transition_issue`	Move an issue to a different workflow status
`add_comment`	Post a comment to an issue
`list_projects`	Return all accessible projects
`get_project`	Get details and metadata for a specific project
`list_transitions`	Show available workflow transitions for an issue

Ask Claude to list what Jira tools are available to confirm your setup: “What Jira tools do you have available?” This confirms the MCP server is loaded and shows you exactly what operations are possible.

Core Operations with Jira MCP Server

Once connected, you can perform fundamental Jira operations through natural language. Creating a new issue requires specifying the project key, issue type, and summary:

Create a bug in PROJECT with summary "Login button not responding on mobile" and description "The login button fails to respond when tapped on iOS devices running iOS 17+. The button renders correctly but the tap target does not register. Affects approximately 15% of our mobile user base."

The MCP server translates this into a proper Jira REST API call, creates the issue, and returns the new ticket key. You can immediately reference this ticket in follow-up requests:

Add labels "mobile" and "p1" to the ticket you just created, and set priority to Critical.

Querying issues uses JQL (Jira Query Language) through the MCP server. You do not need to know JQL syntax, describe the query in natural language and Claude translates it:

Find all unresolved tickets in PROJECT assigned to me with priority High

The server executes the JQL query and returns structured results. For reference, the JQL Claude generates for this request looks like:

project = PROJECT AND assignee = currentUser() AND resolution = Unresolved AND priority = High ORDER BY updated DESC

Understanding the underlying JQL helps you craft more precise natural language queries. Here are common JQL patterns with their natural language equivalents:

Natural Language	JQL Equivalent
“My open tickets this sprint”	`assignee = currentUser() AND sprint in openSprints() AND resolution = Unresolved`
“Bugs created this week”	`issuetype = Bug AND created >= startOfWeek()`
“Tickets blocked by PROJ-100”	`issue in linkedIssues("PROJ-100", "is blocked by")`
“Everything in the backlog with label ‘technical-debt’”	`sprint = EMPTY AND labels = "technical-debt" AND resolution = Unresolved`
“High priority tickets with no assignee”	`priority in (High, Critical) AND assignee is EMPTY AND resolution = Unresolved`
“Tickets updated in the last 24 hours”	`updated >= -1d ORDER BY updated DESC`

This proves invaluable for daily standups or sprint planning when you need quick visibility into your workload without manually building filters in Jira’s UI.

Automating Workflow Transitions

Moving tickets through workflow states represents one of the most common automation opportunities. Instead of manually clicking through Jira’s interface, you can transition issues programmatically:

Transition PROJ-123 to "In Progress" and add comment "Starting development work on this issue. Expected completion by end of sprint."

The combined operation updates status and adds context in a single conversational command. This pattern works well for teams using the supermemory skill to track decision history alongside workflow changes.

Before transitioning, you can ask Claude to check what transitions are available for a ticket:

What workflow transitions are available for PROJ-123?

This is useful when you are unfamiliar with a project’s workflow or when tickets have conditional transitions based on field values.

For bulk operations, you can iterate through multiple tickets:

Move all tickets in the "Sprint 23" sprint with label "ready-for-dev" to "In Progress"

This handles the common scenario where you begin a sprint and need to activate multiple backlog items efficiently. The MCP server executes a JQL search first to find matching tickets, then transitions each one sequentially.

Status Update Patterns for Common Scenarios

Here are practical prompts for the most common workflow scenarios:

Daily standup update:

For each ticket I'm currently working on (assignee = me, status = In Progress), add a comment summarizing that I'm still actively working on it and update the "Progress" field to today's date.

Code review handoff:

Transition PROJ-456 to "In Review", assign it to [email protected], and add a comment "PR is up at https://github.com/org/repo/pull/789. Ready for review."

Blocked ticket documentation:

Transition PROJ-789 to "Blocked", add a blocker link to PROJ-100, and add comment "Waiting on API contract finalization in PROJ-100 before this can proceed."

Closing resolved tickets:

Find all tickets assigned to me in PROJ that have status "Done" but resolution = Unresolved, then set their resolution to "Done".

Creating Custom Automation Patterns

Advanced users can combine Jira MCP with other Claude capabilities for sophisticated workflows.

Development-to-Ticket Automation

Consider a pattern where your TDD workflow identifies missing functionality and automatically creates Jira tickets to track it:

Create a story in PROJECT for "Add user authentication via OAuth2" with acceptance criteria:
- Users can sign in with Google, GitHub, and Microsoft accounts
- Sessions expire after 24 hours of inactivity
- Refresh tokens are stored securely server-side
- OAuth flow completes in under 3 seconds on average

For a team doing rigorous acceptance-criteria-driven development, this prompt structure generates well-formed stories that your QA team can directly translate into test cases.

Generating Sprint Reports

The Jira MCP server enables you to generate reports without leaving your terminal:

Generate a sprint report for Sprint 23 in PROJECT showing:
- Total tickets completed vs planned
- Breakdown by issue type (bug vs story vs task)
- Any tickets that were not completed and their current status
- Average cycle time from "In Progress" to "Done"

Claude queries Jira for each data point and assembles the report. You can then pipe this into a markdown file or paste it into a Confluence page.

Linking Code Changes to Tickets

When committing code that resolves a Jira ticket, close the loop automatically:

I just merged PR #445 which fixes PROJ-234. Transition the ticket to Done, add a comment referencing the PR, and set the "Resolved in Build" field to "v2.4.1".

This keeps your Jira data accurate without manual updates after each merge.

Creating Epics with Story Breakdown

For feature planning, you can create an entire epic with child stories in a single session:

Create an epic in PROJECT called "Payment Processing v2" with description "Upgrade our payment infrastructure to support recurring billing, multi-currency, and real-time fraud detection."
Then create the following stories under that epic:
"Implement recurring billing engine" - story points 8
"Add multi-currency support for USD, EUR, GBP" - story points 5
"Integrate Stripe Radar for fraud detection" - story points 13
"Build payment analytics dashboard" - story points 8
"Write payment API documentation" - story points 3

The MCP server creates the epic first, captures its key, then creates each story linked to the parent epic. This replaces thirty minutes of form-filling with a single structured prompt.

Connecting pdf Skill Output to Jira

The pdf skill complements the Jira MCP by generating specification documents you can attach to tickets:

Generate a technical specification document for PROJ-456 based on its description and acceptance criteria, then attach it to the ticket as a PDF.

This creates a closed loop between development work, project management, and documentation. The ticket becomes a self-contained unit with the specification attached, the PR linked, and the resolution recorded.

Security and Best Practices

Handle your Jira API token carefully. Never commit it to version control. Use environment variables or a secrets manager instead of hardcoding credentials. The MCP server supports reading from environment variables:

{
 "mcpServers": {
 "jira": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-jira"],
 "env": {
 "JIRA_HOST": "${JIRA_HOST}",
 "JIRA_EMAIL": "${JIRA_EMAIL}",
 "JIRA_API_TOKEN": "${JIRA_API_TOKEN}"
 }
 }
 }
}

Set these variables in your shell profile:

~/.zshrc or ~/.bashrc
export JIRA_HOST="yourcompany.atlassian.net"
export JIRA_EMAIL="[email protected]"
export JIRA_API_TOKEN="your-api-token"

For teams sharing development machines or using CI environments, store the API token in a dedicated secrets manager (AWS Secrets Manager, HashiCorp Vault, 1Password Secrets Automation) and inject it at runtime.

Limit MCP server permissions to the minimum required for your workflow. If your Atlassian plan supports scoped API tokens, create a token with read/write access only to the specific projects your automation targets. Avoid using a token tied to an admin account.

Audit and Accountability

When using automation to update tickets in bulk, maintain accountability by including a signature in programmatic comments:

Add comment to PROJ-123: "Status updated automatically by sprint kickoff workflow on 2026-03-22. If this transition is incorrect, please revert and add a comment explaining why."

This makes it clear which changes came from automation versus manual updates, simplifying audits when something goes wrong.

Comparing Jira MCP to Alternative Approaches

The Jira MCP server is not the only way to automate Jira from a development environment. Understanding the trade-offs helps you choose the right tool for different scenarios:

Approach	Setup Effort	Flexibility	Natural Language	Maintenance
Jira MCP + Claude Code	Low	High	Yes	Low
Jira REST API (custom scripts)	High	Very High	No	High
Jira Automation (built-in)	Medium	Medium	No	Low
Zapier/n8n integrations	Medium	Medium	No	Low
Jira CLI (go-jira, jira-cli)	Medium	High	No	Medium

The Jira MCP approach excels at ad-hoc automation and exploratory tasks where you know what you want but do not want to write a script. The Jira REST API directly is better when you need repeatable, version-controlled automation with exact control over every parameter. Jira’s built-in automation rules handle event-driven workflows (e.g., “when PR is merged, transition ticket to Done”) without any external tooling.

Use the MCP server for interactive work and one-off automation. Use scripted REST API calls for repeatable processes that need to run unattended in CI/CD pipelines.

Troubleshooting Common Issues

Connection Failures

Connection failures typically stem from incorrect credentials or network restrictions. Verify your API token has the correct permissions and that your Jira instance allows API access.

Test your credentials directly with curl before debugging Claude configuration
curl -u "[email protected]:your-api-token" \
 "https://yourcompany.atlassian.net/rest/api/3/myself"

If this curl command returns your user details, the credentials are correct. If it fails, regenerate the API token from id.atlassian.com.

Common causes of connection failures:

Wrong JIRA_HOST format: Use yourcompany.atlassian.net without https:// prefix
Email mismatch: The JIRA_EMAIL must exactly match the Atlassian account email, including case
Corporate VPN required: Some Jira instances only allow API access from within the corporate network or VPN
IP allowlisting: Enterprise Atlassian accounts can restrict API access by IP range

Rate Limiting

Rate limiting occurs when you make too many requests in quick succession. The MCP server handles this automatically with exponential backoff, but if you encounter persistent issues, batch your operations using bulk update endpoints.

Atlassian’s rate limits for Jira Cloud are:

10,000 API requests per 10 minutes per user
Burst limit of 100 requests per second

For teams running large bulk operations (transitioning hundreds of tickets), space out operations or use Jira’s native bulk edit features for one-time migrations.

Authentication Errors

Authentication errors often result from expired tokens or account changes. Atlassian API tokens do not expire by default, but:

Changing your Atlassian account password invalidates all API tokens
If your organization enforces token rotation policies, tokens may expire
SSO/SAML configurations can affect API token validity in some enterprise setups

Regenerate the token and update your environment variable to resolve persistent authentication failures.

MCP Server Not Showing in Claude

If Claude does not appear to have Jira tools available after configuration:

Confirm the MCP settings file path: ~/.claude/mcp-servers.json (not mcp_servers.json)
Validate the JSON syntax with a linter, a trailing comma or missing bracket prevents the file from loading
Fully restart Claude Code (not just reload)
Check that npx is available in your PATH by running npx --version in your terminal

Validate JSON syntax
python3 -m json.tool ~/.claude/mcp-servers.json

If the file has syntax errors, this command prints the error location.

Practical Example: Full Sprint Kickoff Workflow

A complete sprint kickoff demonstrates the integration’s power. Rather than individual commands, structure this as a multi-step workflow:

Sprint 24 kickoff:
Find all stories in PROJECT with fixVersion "Sprint 24" and status "Ready for Development"
Transition each to "In Progress"
For each story, create a subtask called "Code Review" and assign it to the story's current assignee
Add a comment to the Sprint 24 epic: "Sprint 24 kicked off on 2026-03-22. X stories activated."
Find any stories still in status "To Do" with no assignee and post a summary of them so I can assign them in standup

This sequence handles your sprint activation in seconds rather than minutes of manual clicking. The summary at the end gives you immediate visibility into unassigned work before the standup meeting.

Post-Sprint Retrospective Data Collection

At sprint end, gather retrospective data automatically:

For Sprint 23 in PROJECT:
List all tickets that were in scope (fixVersion = Sprint 23)
Show how many completed vs. carried over
Show which tickets had their story points changed mid-sprint
List all bugs opened during the sprint that weren't in the original scope
Calculate the percentage of sprint capacity consumed by unplanned work (bugs vs. original stories)

This gives your retrospective a data-driven foundation without anyone spending time manually compiling numbers from Jira before the meeting.

The Jira MCP server transforms how you interact with project management tooling. By bringing Jira operations directly into your Claude Code workflow, you maintain focus on development while keeping project tracking current and accurate. The patterns in this guide represent a starting point, as you use the integration, you will discover automation opportunities specific to your team’s workflow that reduce friction and keep your Jira data clean and current.

Generating Sprint Reports with Claude Code

Once Jira data flows into Claude Code via the MCP server, generating sprint reports becomes a natural language task rather than a manual export process. This is one of the highest-value uses of the integration for team leads and project managers.

Ask Claude to pull the sprint data and format it as a report:

Fetch all completed stories in Sprint 24 from PROJECT.
For each story, include the story points, assignee, and resolution date.
Calculate total velocity and compare it to Sprint 23's velocity.
Format the results as a markdown table suitable for our Confluence weekly update.

Claude retrieves the JQL results, performs the calculations, and formats the output. The entire report takes seconds instead of the 20-30 minutes typically spent clicking through Jira’s built-in reports.

For recurring reports, save effective prompts as custom Claude Code skills. A skill file for weekly sprint reporting keeps the prompt consistent across team members:

Sprint Report Skill
When invoked, generate a weekly sprint report:
Query current sprint tickets with: project = PROJECT AND sprint in openSprints()
Calculate completion percentage and velocity
Identify any tickets blocked more than 3 days
Format as a Confluence-ready table with emoji status indicators
Include a one-paragraph executive summary

Save this as ~/.claude/skills/sprint-report.md and any team member can run /sprint-report to produce a standardized output each Friday.

Linking Commits to Jira Tickets Automatically

Developer workflows improve when Git commits reference Jira tickets consistently. Claude Code can assist with enforcing this practice and creating the links retroactively when they are missing.

Configure a Git commit message template that includes the Jira ticket:

.gitmessage template
[PROJ-XXX] Brief description of change
#
Why: Explain the business context
How: Technical summary of the approach
#
Jira: PROJ-XXX

When you forget to include a ticket reference, Claude can query Jira for tickets matching the commit’s work area and suggest the correct link:

Look at my last 5 commits without Jira ticket references and find the
most likely matching tickets from open tickets in PROJECT.
Use the commit message content to match against ticket summaries.

This retroactive linking keeps your Jira boards accurate without requiring developers to switch context mid-coding session to find and record ticket numbers.

Managing Multiple Jira Projects

Teams working across multiple Jira projects can configure the MCP server to access all of them simultaneously. The configuration supports multiple project contexts in a single session:

Show all P1 tickets assigned to me across all projects I have access to,
grouped by project key and sorted by creation date.

For organizations using both Jira Cloud and Jira Server, the MCP server requires separate configuration entries. one per Jira instance. Name them clearly in your mcp-servers.json:

{
 "mcpServers": {
 "jira-cloud": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-jira"],
 "env": {
 "JIRA_HOST": "yourcompany.atlassian.net",
 "JIRA_EMAIL": "${JIRA_CLOUD_EMAIL}",
 "JIRA_API_TOKEN": "${JIRA_CLOUD_TOKEN}"
 }
 },
 "jira-server": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-jira"],
 "env": {
 "JIRA_HOST": "jira.internal.yourcompany.com",
 "JIRA_EMAIL": "${JIRA_SERVER_EMAIL}",
 "JIRA_API_TOKEN": "${JIRA_SERVER_TOKEN}"
 }
 }
 }
}

When querying, specify which server to use: “Using jira-cloud, find all tickets…” This distinction matters for teams migrating from Server to Cloud who run both instances during the transition period.

Try it: Paste your error into our Error Diagnostic for an instant fix.

I hit this exact error six months ago. Then I wrote a CLAUDE.md that tells Claude my stack, my conventions, and my error handling patterns. Haven't seen it since. I run 5 Claude Max subs, 16 Chrome extensions serving 50K users, and bill $500K+ on Upwork. These CLAUDE.md templates are what I actually use. Not theory — production configs. **[Grab the templates — $99 once, free forever →](https://zovo.one/lifetime?utm_source=ccg&utm_medium=cta-mcp&utm_campaign=jira-mcp-server-claude-code-integration-guide)** 47/500 founding spots. Price goes up when they're gone.