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",
        "[email protected]",
        "--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": "[email protected]",
        "jiraApiToken": "your-api-token"
      }
    }
  }
}

Option 3: Local Development

npm install @quialorraine/jira-mcp-server

🔧 Configuration

Getting Your Atlassian API Token

1. Go to Atlassian 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)

JIRA_BASE_URL=https://your-domain.atlassian.net
[email protected]
JIRA_API_TOKEN=your-api-token

Command Line Arguments

npx @quialorraine/jira-mcp-server \
  --jira-base-url=https://your-domain.atlassian.net \
  [email protected] \
  --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: "[email protected]" }
  }
});

🔍 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

1. Create Heroku App:

heroku create your-jira-mcp-server

2. Set Environment Variables:

heroku config:set JIRA_BASE_URL=https://your-domain.atlassian.net
heroku config:set [email protected]
heroku config:set JIRA_API_TOKEN=your-api-token

3. 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 [email protected] \
  -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 Contributing Guide for details.

Quick start:

1. Fork the repository
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

Made with ❤️ for the MCP ecosystem