Jira MCP Server

Fork of OrenGrinker/jira-mcp-server

A production-ready Model Context Protocol (MCP) server for Jira integration. Supports both Jira Cloud and Jira Data Center/Server with comprehensive issue management, board operations, time tracking, and project management capabilities.

Features

Core Functionality

• Board Management: List, filter, and manage Jira boards with detailed information
• Issue Operations: Create, update, search, transition, and manage issues comprehensively
• User Management: Search users, get user details, and manage assignments
• Project Administration: View projects, get detailed project information
• Time Tracking: Add and view work logs with flexible time formats
• Comment System: Add comments with rich text support

Enhanced Features

• Dual Authentication: Supports both Jira Cloud (Basic Auth) and Jira Data Center/Server (Bearer Token)
• Rate Limiting: Intelligent API request throttling to respect Jira limits
• Request Timeout: Built-in 30-second timeout with AbortController
• Comprehensive Logging: Configurable logging with multiple levels
• Error Handling: Robust error handling with sanitized error messages
• Input Validation: Thorough validation and sanitization of all inputs
• Security: HTTPS enforcement, SSRF protection, sensitive data sanitization

Requirements

• Node.js: 18.0.0 or higher
• Jira: Access to a Jira Cloud or Jira Data Center/Server instance
• API Token:
  • Jira Cloud: Create API Token
  • Jira Server: Personal Access Token (Profile → Personal Access Tokens)

Installation

Option 1: Clone and Build

git clone https://github.com/JSM-CN/jira-mcp-server.git
cd jira-mcp-server
npm install
npm run build

Option 2: Use Directly with npx

npx @jsm-cn/jira-mcp-server

Configuration

Environment Variables

Create a .env file or set these environment variables:

Jira Cloud

JIRA_BASE_URL=https://your-company.atlassian.net
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=your-jira-api-token
JIRA_AUTH_TYPE=cloud
LOG_LEVEL=INFO  # Optional: ERROR, WARN, INFO, DEBUG

Jira Data Center/Server

JIRA_BASE_URL=https://jira.your-company.com
JIRA_API_TOKEN=your-personal-access-token
JIRA_AUTH_TYPE=server
LOG_LEVEL=INFO

Variable	Required	Description
JIRA_BASE_URL	Yes	Your Jira instance URL (must use HTTPS)
JIRA_API_TOKEN	Yes	API token (Cloud) or Personal Access Token (Server)
JIRA_EMAIL	Cloud only	Your Jira account email
JIRA_AUTH_TYPE	No	cloud (default) or server
LOG_LEVEL	No	Logging level: ERROR, WARN, INFO, DEBUG

Claude Code Configuration

Add to your ~/.claude/settings.json:

{
  "env": {
    "JIRA_BASE_URL": "https://your-company.atlassian.net",
    "JIRA_EMAIL": "your-email@company.com",
    "JIRA_API_TOKEN": "your-api-token",
    "JIRA_AUTH_TYPE": "cloud"
  }
}

And create ~/.mcp.json:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jira-mcp-server/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "${JIRA_BASE_URL}",
        "JIRA_EMAIL": "${JIRA_EMAIL}",
        "JIRA_API_TOKEN": "${JIRA_API_TOKEN}",
        "JIRA_AUTH_TYPE": "${JIRA_AUTH_TYPE}",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Available Tools

Tool	Description
get_boards	List all boards with optional filtering
get_board_details	Get detailed board information
get_board_issues	Get issues from a board with filters
search_issues	Search issues using JQL
get_issue_details	Get comprehensive issue information
create_issue	Create a new issue
update_issue	Update an existing issue
transition_issue	Move issue to a different status
add_comment	Add a comment to an issue
get_current_user	Get authenticated user info
search_users	Find users by name or email
get_user_details	Get detailed user information
get_projects	List all accessible projects
get_project_details	Get project information
add_worklog	Log work time on an issue
get_worklogs	View work logs for an issue
get_server_info	Get Jira server information

Usage Examples

Natural Language Commands with Claude

"Show me all my open issues"
"Create a new bug in PROJECT-X about login issues"
"Move ticket PROJ-123 to In Progress"
"Log 2 hours of work on PROJ-456 for code review"
"Add a comment to PROJ-789 saying the fix is deployed"
"Show me all Scrum boards for the mobile project"
"Get details for issue PROJ-100 including comments"

JQL Query Examples

# Your open issues
assignee = currentUser() AND status != Done

# Recent issues in a project
project = "MYPROJ" AND created >= -7d

# High priority bugs
priority = High AND issuetype = Bug

# Issues due this week
duedate >= startOfWeek() AND duedate <= endOfWeek()

Security Features

This server implements multiple security measures:

• HTTPS Enforcement: All connections must use HTTPS
• SSRF Protection: Blocks requests to private IP addresses (10.x, 172.16-31.x, 192.168.x, localhost)
• Input Sanitization: JQL injection prevention and input length limits
• Credential Protection: Sensitive data is redacted in logs and error messages
• Request Timeout: 30-second timeout prevents resource exhaustion

Development

Setup

git clone https://github.com/JSM-CN/jira-mcp-server.git
cd jira-mcp-server
npm install

Scripts

npm run dev      # Start development server with hot reload
npm run build    # Build for production
npm run clean    # Clean build directory
npm run start    # Start production server

Project Structure

src/
├── index.ts              # Main server entry point
├── jiraApiClient.ts      # Jira API client with auth support
├── toolRegistry.ts       # Tool registration and routing
├── types/
│   └── index.ts         # TypeScript type definitions
├── services/
│   ├── boardService.ts   # Board operations
│   ├── issueService.ts   # Issue operations
│   ├── userService.ts    # User operations
│   ├── projectService.ts # Project operations
│   ├── worklogService.ts # Worklog operations
│   └── serverService.ts  # Server operations
└── utils/
    ├── logger.ts        # Logging utility
    ├── rateLimiter.ts   # Rate limiting
    ├── validation.ts    # Input validation
    └── formatters.ts    # Response formatting

Troubleshooting

Common Issues

Issue	Solution
Authentication Failed	Verify API token and email (Cloud) or PAT (Server)
Permission Denied	Check Jira permissions for your user
Connection Timeout	Check network connectivity and firewall settings
401 Error on Jira Server	Use Personal Access Token, not Cloud API Token

Debug Mode

export LOG_LEVEL=DEBUG

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with the Model Context Protocol SDK
• Inspired by the MCP community and best practices