mcp-jira

MCP server for Jira integration - Create, read, update issues and manage projects through Claude.

Version 1.2.0 - Full CRUD operations for Jira issues including create, update, transition, and comment

🚀 Quick Start

# Install with your Jira credentials
claude mcp add jira -s user \
  -e JIRA_DOMAIN=your-domain.atlassian.net \
  -e [email protected] \
  -e JIRA_API_TOKEN=your-api-token \
  -- npx @chinchillaenterprises/mcp-jira

Then start Claude and try: "Search for all open issues assigned to me"

Prerequisites

Before using this MCP server, you need:

1. Jira Account: Access to a Jira instance (Cloud or Server)
2. API Token: Create one at https://id.atlassian.com/manage-profile/security/api-tokens
3. Permissions: Read access to projects and issues you want to work with

Installation

NPM Installation (Recommended)

claude mcp add jira -s user \
  -e JIRA_DOMAIN=chinchilla-ai.atlassian.net \
  -e [email protected] \
  -e JIRA_API_TOKEN=your-api-token \
  -- npx @chinchillaenterprises/mcp-jira

Local Development Installation

# Build the project
cd mcp-jira
npm install
npm run build

# Add to Claude Code
claude mcp add jira-dev -s user \
  -e JIRA_DOMAIN=chinchilla-ai.atlassian.net \
  -e [email protected] \
  -e JIRA_API_TOKEN=your-api-token \
  -- node /absolute/path/to/mcp-jira/dist/index.js

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | JIRA_DOMAIN | Yes | Your Jira instance domain (e.g., company.atlassian.net) | | JIRA_EMAIL | Yes | Email associated with your Jira account | | JIRA_API_TOKEN | Yes | API token from Atlassian account settings |

Available Tools

jira_create_issue

Create a new issue in Jira with automatic user lookup and field validation.

Parameters:

• project_key (required): Project key (e.g., "CHINCHILLA")
• summary (required): Issue title/summary
• description (optional): Detailed issue description
• issue_type (optional): Type of issue - defaults to "Task" (e.g., "Bug", "Story", "Task")
• assignee (optional): Email address or "me" for current user
• priority (optional): Priority level (e.g., "High", "Medium", "Low")
• labels (optional): Array of labels to add

Examples:

Create a new task in project CHINCHILLA titled "Add user authentication"
Create a high priority bug in NUWA project assigned to me
Create a story with description "As a user, I want to..." and label it "frontend"

jira_search_issues

Search for issues using JQL (Jira Query Language).

Parameters:

• jql (required): JQL query string
• max_results (optional): Maximum number of results (default: 50)

Examples:

Search for all issues in project ABC that are in progress
Search for bugs assigned to me in the last week
Find all high priority issues in sprint 5

jira_get_issue

Get complete details of a specific issue.

Parameters:

• issue_key (required): Issue key (e.g., "ABC-123")

Example:

Get details for issue PROJ-456
Show me everything about ticket ABC-123

jira_list_projects

List all projects you have access to.

Parameters:

• expand (optional): Comma-separated fields to include (e.g., "description,lead")

Example:

List all Jira projects
Show me all projects with their descriptions

jira_get_my_issues

Get all issues assigned to you.

Parameters:

• status (optional): Filter by status (e.g., "In Progress", "Open")

Example:

What Jira issues are assigned to me?
Show me my in progress tickets
List all my open issues

jira_list_issue_comments

Get all comments on a specific issue.

Parameters:

• issue_key (required): Issue key (e.g., "ABC-123")
• max_results (optional): Maximum number of comments (default: 50)

Example:

Show all comments on issue PROJ-789
Get the discussion history for ABC-123

jira_update_issue

Update fields of an existing issue.

Parameters:

• issue_key (required): Issue key to update (e.g., "ABC-123")
• summary (optional): New issue title
• description (optional): New issue description
• assignee (optional): New assignee (email, "me", or "unassigned")
• priority (optional): New priority
• labels (optional): Replace all labels
• add_labels (optional): Add labels (keeps existing)
• remove_labels (optional): Remove specific labels

Examples:

Update issue PROJ-123 to have high priority
Change the assignee of ABC-456 to me
Add labels "backend" and "api" to issue DEF-789
Update the summary of GHI-012 to "Fix authentication bug"

jira_transition_issue

Move an issue to a different workflow state.

Parameters:

• issue_key (required): Issue key (e.g., "ABC-123")
• transition_name (required): Target status name (e.g., "In Progress", "Done")
• comment (optional): Comment to add with the transition

Examples:

Move issue PROJ-123 to In Progress
Transition ABC-456 to Done with comment "Fixed in PR #789"
Change status of DEF-789 to Code Review

jira_add_comment

Add a comment to an issue.

Parameters:

• issue_key (required): Issue key (e.g., "ABC-123")
• comment (required): Comment text
• visibility (optional): Restrict visibility to group or role

Examples:

Add comment "Working on this now" to issue PROJ-123
Comment on ABC-456 saying "Need more information about the requirements"
Add a note to DEF-789 about the proposed solution

Usage Examples

Basic JQL Searches

"Search for all issues in project PROJ where status is 'To Do'"
"Find all bugs created in the last 7 days"
"Show me issues assigned to me that are due this week"
"List all issues with label 'urgent' that aren't closed"

Common JQL Patterns

# My open issues
assignee = currentUser() AND resolution = Unresolved

# Issues in current sprint
sprint in openSprints()

# High priority bugs
priority = High AND issuetype = Bug

# Recently updated
updated >= -7d ORDER BY updated DESC

# Issues in specific project and status
project = ABC AND status in ("In Progress", "Review")

Working with Issues

"Get full details for issue PROJ-123"
"Show me all comments on the latest bug report"
"What are my highest priority issues right now?"
"List all projects I have access to"

Troubleshooting

Common Issues

1. Authentication Failed

   • Verify your API token is correct
   • Check that your email matches the Jira account
   • Ensure the token hasn't expired

2. Permission Denied

   • Confirm you have access to the project/issue
   • Check if your account has the necessary permissions

3. Resource Not Found

   • Verify the issue key is correct
   • Check if the project exists
   • Ensure you're using the right Jira domain

4. Invalid JQL

   • Check JQL syntax (use quotes for multi-word values)
   • Verify field names are correct
   • Test the query in Jira's issue search first

Debug Mode

Run Claude Code with debug flag to see detailed logs:

claude --mcp-debug

Development

Building from Source

# Clone the repository
git clone https://github.com/chinchillaenterprises/ChillMCP.git
cd ChillMCP/mcp-jira

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

Future Enhancements

Planned features for future versions:

• Attach files to issues
• Bulk operations (create/update multiple issues)
• Sprint management (create sprints, move issues between sprints)
• Custom field support
• Webhook integration for real-time updates
• Advanced search with saved filters
• Time tracking (log work, estimates)
• Issue watchers management

Security Considerations

• Never commit API tokens: Store them as environment variables only
• Use read-only tokens when possible for safety
• Rotate tokens regularly as a security best practice
• Limit permissions to only what's needed for your use case

License

MIT License - see the parent repository for details.

Support

For issues and feature requests, please visit the ChillMCP repository.

Built with ❤️ by Chinchilla Enterprises