jira-mcp-server by indrajithi - MCP Server

Jira MCP Server

A comprehensive Model Context Protocol (MCP) server for complete Jira project management integration with Claude Code.

✨ Features

🎯 Core Issue Management

jira_search: Search for Jira issues using JQL or simple filters
jira_get_issue: Get detailed information about a specific issue
jira_create_issue: Create new Jira issues
jira_update_issue: Update existing issues with new information
jira_delete_issue: Delete issues permanently (with safety confirmation)
jira_assign_issue: Assign or unassign issues to users

🔄 Workflow Management

jira_transition_issue: Change issue status through workflow transitions
jira_get_transitions: Get available transitions for any issue

💬 Comment Management

jira_add_comment: Add comments to issues for collaboration
jira_get_comments: Retrieve all comments from an issue

🏃‍♂️ Sprint Management

jira_create_sprint: Create new sprints on boards
jira_get_sprints: List all sprints for a board (with state filtering)
jira_get_sprint_analytics: Get detailed sprint metrics and analytics

📊 Project Information

jira_list_projects: List all accessible projects
jira_get_project_info: Get detailed project information and statistics

Setup

Install dependencies:
```
npm install
```

Configure environment: Copy .env and update with your Jira credentials:

JIRA_URL=https://your-company.atlassian.net
JIRA_USERNAME=your.email@company.com
JIRA_API_TOKEN=your_api_token
JIRA_PROJECT_KEY=AR

Build and run:
```
npm run build
npm start
```
Or for development:
```
npm run dev
```

Claude Code Integration

The server is registered globally with user scope:

claude mcp add --scope user jira-mcp-server /path/to/dist/index.js

📚 Usage Examples

Core Issue Management

// Search all issues in project
jira_search({ project: "AR" })

// Search with JQL
jira_search({ jql: "status = 'To Do' AND priority = High" })

// Get issue details
jira_get_issue({ issueKey: "AR-1" })

// Create new issue
jira_create_issue({
  summary: "Fix login bug",
  description: "Users cannot log in with valid credentials",
  issueType: "Bug",
  priority: "High"
})

// Update existing issue
jira_update_issue({
  issueKey: "AR-1",
  summary: "Updated summary",
  priority: "Critical"
})

// Assign issue
jira_assign_issue({
  issueKey: "AR-1",
  assignee: "user@company.com"
})

// Delete issue (use with caution!)
jira_delete_issue({
  issueKey: "AR-1",
  confirm: true,
  deleteSubtasks: false
})

Workflow Management

// Get available transitions
jira_get_transitions({ issueKey: "AR-1" })

// Transition issue with comment
jira_transition_issue({
  issueKey: "AR-1",
  transitionId: "21",
  comment: "Moving to In Progress as work has started"
})

Comment Management

// Add comment
jira_add_comment({
  issueKey: "AR-1",
  comment: "This issue is ready for testing"
})

// Get all comments
jira_get_comments({ issueKey: "AR-1" })

Sprint Management

// Create new sprint
jira_create_sprint({
  name: "Sprint 15",
  boardId: 5,
  goal: "Complete user authentication features",
  startDate: "2025-06-18",
  endDate: "2025-07-01"
})

// Get all sprints for board
jira_get_sprints({ boardId: 5 })

// Get sprint analytics
jira_get_sprint_analytics({ sprintId: 123 })

Project Information

// List all projects
jira_list_projects({ includeDetails: true })

// Get project details
jira_get_project_info({ projectKey: "AR" })

🔄 Complete Project Management Workflows

Epic to Sprint Workflow

// 1. List projects and get project info
jira_list_projects()
jira_get_project_info({ projectKey: "AR" })

// 2. Create issues for your epic
jira_create_issue({
  summary: "User Authentication Epic",
  description: "Complete user authentication system",
  issueType: "Epic"
})

// 3. Create sprint and add issues
jira_create_sprint({
  name: "Authentication Sprint 1",
  boardId: 5,
  goal: "Implement login functionality"
})

// 4. Move issues through workflow
jira_get_transitions({ issueKey: "AR-5" })
jira_transition_issue({
  issueKey: "AR-5",
  transitionId: "21",
  comment: "Starting development"
})

// 5. Add progress updates
jira_add_comment({
  issueKey: "AR-5",
  comment: "Backend API implemented, testing in progress"
})

// 6. Monitor sprint progress
jira_get_sprint_analytics({ sprintId: 123 })

Issue Lifecycle Management

// Create → Assign → Update → Transition → Comment → Complete
jira_create_issue({ summary: "Fix login validation" })
jira_assign_issue({ issueKey: "AR-6", assignee: "dev@company.com" })
jira_update_issue({ issueKey: "AR-6", priority: "High" })
jira_transition_issue({ issueKey: "AR-6", transitionId: "21" })
jira_add_comment({ issueKey: "AR-6", comment: "Fix deployed to staging" })
jira_transition_issue({ issueKey: "AR-6", transitionId: "31" })

🏗️ Architecture

src/
├── index.ts           # Main MCP server with all tool handlers
├── types/jira.ts      # Comprehensive TypeScript types and schemas
├── utils/
│   ├── config.ts      # Configuration loading with absolute paths
│   └── jira-client.ts # Extended Jira API client with agile support
└── tools/             # Complete MCP tool implementations
    ├── jira-search.ts
    ├── jira-get-issue.ts
    ├── jira-create-issue.ts
    ├── jira-update-issue.ts
    ├── jira-delete-issue.ts
    ├── jira-assign-issue.ts
    ├── jira-transition-issue.ts
    ├── jira-comments.ts
    ├── jira-sprint-management.ts
    └── jira-project-info.ts

Configuration

Variable	Description	Required
`JIRA_URL`	Jira instance URL	Yes
`JIRA_USERNAME`	Your email address	Yes
`JIRA_API_TOKEN`	API token from Jira	Yes
`JIRA_PROJECT_KEY`	Default project (e.g., "AR")	No
`MCP_VERBOSE`	Enable verbose logging	No
`API_TIMEOUT`	Request timeout in ms	No

Troubleshooting

Authentication errors: Verify API token is valid
Permission errors: Check Jira project permissions
Connection issues: Verify Jira URL and network access

License

MIT