npm package: @quialorraine/jira-mcp-server
Description: MCP server for Jira integration - create and manage Jira issues
Author: quialorraine
Latest version: 1.0.3

# Jira MCP Server

[![npm version](https://badge.fury.io/js/%40quialorraine%2Fjira-mcp-server.svg)](https://badge.fury.io/js/%40quialorraine%2Fjira-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.x-green.svg)](https://nodejs.org/)
[![GitHub issues](https://img.shields.io/github/issues/quialorraine/jira-mcp-server)](https://github.com/quialorraine/jira-mcp-server/issues)
[![GitHub stars](https://img.shields.io/github/stars/quialorraine/jira-mcp-server)](https://github.com/quialorraine/jira-mcp-server/stargazers)

A comprehensive **Model Context Protocol (MCP)** server for **Jira integration**, enabling seamless issue management, comments handling, and JQL searches through AI assistants like Claude and Cursor.

## 🚀 Features

- **Complete Issue Management**: Create, read, update, and delete Jira issues
- **Comments System**: Full comment lifecycle management (add, update, delete)
- **Advanced Search**: JQL-powered issue search with filtering
- **Multiple Deployment Options**: Direct MCP server or HTTP server integration
- **Flexible Authentication**: Command-line, environment variables, or HTTP request configuration
- **ADF Support**: Native Atlassian Document Format parsing for rich text content
- **TypeScript**: Full type safety and IntelliSense support

## 📦 Installation

### Option 1: Direct MCP Server (Recommended for Cursor)

Add to your `~/.cursor/mcp.json` or equivalent MCP configuration:

```json
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": [
        "-y",
        "@quialorraine/jira-mcp-server",
        "--jira-base-url=https://your-domain.atlassian.net",
        "--jira-email=your-email@example.com",
        "--jira-api-token=your-api-token",
        "--stdio"
      ]
    }
  }
}
```

### Option 2: HTTP Server Integration

For remote deployments (e.g., Heroku):

```json
{
  "mcpServers": {
    "jira": {
      "type": "http",
      "url": "https://your-heroku-app.herokuapp.com/mcp",
      "initParams": {
        "jiraBaseUrl": "https://your-domain.atlassian.net",
        "jiraEmail": "your-email@example.com",
        "jiraApiToken": "your-api-token"
      }
    }
  }
}
```

### Option 3: Local Development

```bash
npm install @quialorraine/jira-mcp-server
```

## 🔧 Configuration

### Getting Your Atlassian API Token

1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click **"Create API token"**
3. Enter a label for your token
4. Copy the token (shown only once!)

### Configuration Methods

**Priority**: HTTP Request Parameters > Command Line > Environment Variables

#### Environment Variables (.env)
```env
JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-api-token
```

#### Command Line Arguments
```bash
npx @quialorraine/jira-mcp-server \
  --jira-base-url=https://your-domain.atlassian.net \
  --jira-email=your-email@example.com \
  --jira-api-token=your-api-token \
  --stdio
```

## 🛠 Available Tools

### Issue Management

#### `jira_create_issue`
Create a new Jira issue.

```typescript
{
  projectKey: "PROJ",           // Required: Project key
  summary: "Issue title",       // Required: Issue summary
  description: "Description",   // Optional: Issue description
  issueType: "Task",           // Optional: Issue type (default: Task)
  fields: {}                   // Optional: Additional fields
}
```

#### `jira_get_issue`
Retrieve detailed information about an issue.

```typescript
{
  issueKey: "PROJ-123",        // Required: Issue key
  fields: ["summary", "status"], // Optional: Specific fields
  includeComments: true,       // Optional: Include comments (default: true)
  format: "text"              // Optional: "text", "html", "raw"
}
```

#### `jira_update_issue`
Update an existing issue.

```typescript
{
  issueKey: "PROJ-123",       // Required: Issue key
  fields: {                   // Required: Fields to update
    summary: "New title",
    description: "New description"
  }
}
```

#### `jira_delete_issue`
Delete an issue.

```typescript
{
  issueKey: "PROJ-123"        // Required: Issue key
}
```

#### `jira_search_issues`
Search issues using JQL (Jira Query Language).

```typescript
{
  jql: "project = PROJ AND status = 'In Progress'", // Required: JQL query
  maxResults: 50,                                   // Optional: Max results (default: 50)
  fields: ["summary", "status", "assignee"],        // Optional: Specific fields
  format: "text"                                    // Optional: Output format
}
```

### Comment Management

#### `jira_add_comment`
Add a comment to an issue.

```typescript
{
  issueKey: "PROJ-123",       // Required: Issue key
  text: "Comment text",       // Optional: Plain text comment
  body: {}                    // Optional: ADF body object
}
```

#### `jira_update_comment`
Update an existing comment.

```typescript
{
  issueKey: "PROJ-123",       // Required: Issue key
  commentId: "12345",         // Required: Comment ID
  text: "Updated text",       // Optional: Plain text
  body: {}                    // Optional: ADF body object
}
```

#### `jira_delete_comment`
Delete a comment.

```typescript
{
  issueKey: "PROJ-123",       // Required: Issue key
  commentId: "12345"          // Required: Comment ID
}
```

## 💡 Usage Examples

### Create and Track a Bug

```typescript
// Create a bug report
const bug = await jira_create_issue({
  projectKey: "BUGS",
  summary: "Login button not responsive on mobile",
  description: "Users report that the login button doesn't respond to clicks on mobile devices (iOS Safari, Android Chrome)",
  issueType: "Bug"
});

// Add investigation comment
await jira_add_comment({
  issueKey: bug.key,
  text: "Investigating CSS media queries and touch event handlers"
});

// Search related issues
const relatedIssues = await jira_search_issues({
  jql: `project = BUGS AND summary ~ "mobile" AND status != Done`,
  maxResults: 10
});
```

### Sprint Planning Workflow

```typescript
// Find stories ready for sprint
const sprintCandidates = await jira_search_issues({
  jql: `project = DEV AND status = "Ready for Sprint" AND "Story Points" <= 8`,
  fields: ["summary", "customfield_storypoints", "priority"],
  maxResults: 20
});

// Update story status
await jira_update_issue({
  issueKey: "DEV-456",
  fields: {
    status: { name: "In Progress" },
    assignee: { emailAddress: "developer@company.com" }
  }
});
```

## 🔍 JQL Examples

```typescript
// Recently updated issues
await jira_search_issues({
  jql: "updated >= -7d ORDER BY updated DESC"
});

// My assigned high-priority issues
await jira_search_issues({
  jql: "assignee = currentUser() AND priority = High AND status != Done"
});

// Issues with specific labels
await jira_search_issues({
  jql: "labels in (urgent, customer-facing) AND created >= -14d"
});
```

## 🛠 Development

### Local Development Setup

```bash
# Clone the repository
git clone https://github.com/quialorraine/jira-mcp-server.git
cd jira-mcp-server

# Install dependencies
npm install

# Create environment file
cp env.example .env
# Edit .env with your Jira credentials

# Start development server
npm run dev

# Start HTTP server for testing
npm run http
```

### Build Process

```bash
# Compile TypeScript
npm run build

# Start production server
npm start

# Run HTTP server
npm run http
```

## 🌐 Deployment

### Heroku Deployment

1. **Create Heroku App**:
```bash
heroku create your-jira-mcp-server
```

2. **Set Environment Variables**:
```bash
heroku config:set JIRA_BASE_URL=https://your-domain.atlassian.net
heroku config:set JIRA_EMAIL=your-email@example.com
heroku config:set JIRA_API_TOKEN=your-api-token
```

3. **Deploy** (connect your GitHub repository to Heroku)

### Docker Deployment

```bash
# Build image
docker build -t jira-mcp-server .

# Run container
docker run -p 3000:3000 \
  -e JIRA_BASE_URL=https://your-domain.atlassian.net \
  -e JIRA_EMAIL=your-email@example.com \
  -e JIRA_API_TOKEN=your-api-token \
  jira-mcp-server
```

## 🚨 Troubleshooting

### Common Issues

**Authentication Error (401)**
- Verify your email and API token are correct
- Ensure the API token was generated for the correct Atlassian account

**Project Not Found (404)**
- Verify the project key exists and you have permission to access it

**Permission Denied (403)**
- Ensure your account has appropriate permissions for the action

## 📋 Requirements

- **Node.js**: >= 18.x
- **Jira**: Cloud instance with REST API access
- **Atlassian Account**: With API token generation capability

## 📧 Support

For issues and questions:
- [Create an issue](https://github.com/quialorraine/jira-mcp-server/issues/new) on GitHub
- [Check existing issues](https://github.com/quialorraine/jira-mcp-server/issues) for solutions
- Review [Jira API documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v3/) for API-related questions

## 📄 License

MIT License

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

Quick start:
1. [Fork the repository](https://github.com/quialorraine/jira-mcp-server/fork)
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. [Open a Pull Request](https://github.com/quialorraine/jira-mcp-server/compare)

---

**Made with ❤️ for the MCP ecosystem**