jira-mcp-server by quialorraine - MCP Server

Jira MCP Server

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:

{
  "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):

{
  "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

npm install @quialorraine/jira-mcp-server

🔧 Configuration

Getting Your Atlassian API Token

Go to Atlassian API Tokens
Click "Create API token"
Enter a label for your token
Copy the token (shown only once!)

Configuration Methods

Priority: HTTP Request Parameters > Command Line > Environment Variables

Environment Variables (.env)

JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-api-token

Command Line Arguments

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.

{
  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.

{
  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.

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

`jira_delete_issue`

Delete an issue.

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

`jira_search_issues`

Search issues using JQL (Jira Query Language).

{
  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.

{
  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.

{
  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.

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

💡 Usage Examples

Create and Track a Bug

// 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

// 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

// 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

# 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

# Compile TypeScript
npm run build

# Start production server
npm start

# Run HTTP server
npm run http

🌐 Deployment

Heroku Deployment

Create Heroku App:

heroku create your-jira-mcp-server

Set Environment Variables:

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

Deploy (connect your GitHub repository to Heroku)

Docker Deployment

# 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 on GitHub
Check existing issues for solutions
Review Jira API documentation for API-related questions

📄 License

MIT License

🤝 Contributing

We welcome contributions! Please see our for details.

Quick start:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Made with ❤️ for the MCP ecosystem