Jira MCP Server

A comprehensive, production-ready Model Context Protocol (MCP) server for seamless Jira Cloud integration. This enhanced version provides advanced features, robust error handling, and extensive tooling for AI agents, automation systems, and custom applications.

Note: This is a fork of @orengrinker/jira-mcp-server with custom modifications. Original work by Oren Grinker.

🚀 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 (ADF format)
• Server Information: Monitor server status and health

Enhanced Features

• ⚡️ Performance Optimization: Optimized issue retrieval with single-request grouped results (5-6x faster)
• Rate Limiting: Intelligent API request throttling to respect Jira limits
• Comprehensive Logging: Configurable logging with multiple levels
• Error Handling: Robust error handling with detailed error messages
• Input Validation: Thorough validation of environment variables and inputs
• Modular Architecture: Clean, maintainable codebase with service-based architecture
• TypeScript Support: Full TypeScript implementation with comprehensive type definitions
• Rich Formatting: Beautiful markdown tables and formatted responses with direct Jira links
• Advanced Search: Support for complex JQL queries with helpful examples
• AI-Powered Workflows: Automatic workflow handling and AI-generated resolutions for issue completion
• Issue Tracking: Smart issue tracking for context-aware operations

🛠️ Requirements

• Node.js: 18.0.0 or higher
• Jira Cloud: Access to a Jira Cloud instance
• API Token: Jira API Token (create here)

⚙️ Environment Variables

Create a .env file or set these environment variables:

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

🚀 Quick Start

Option 1: Using npx (Recommended)

# Run directly without installation
npx @orengrinker/jira-mcp-server

# With environment variables
JIRA_BASE_URL=https://company.atlassian.net \
JIRA_EMAIL=user@company.com \
JIRA_API_TOKEN=your-token \
npx @orengrinker/jira-mcp-server

Option 2: Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["@orengrinker/jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Option 3: Global Installation

npm install -g @orengrinker/jira-mcp-server
jira-mcp-server

Option 4: Local Development

git clone https://github.com/OrenGrinker/jira-mcp-server.git
cd jira-mcp-server
npm install
npm run build
node dist/index.js

🧰 Available Tools

Board Tools

• get_boards - List all boards with optional filtering by type and project
• get_board_details - Get comprehensive board information
• get_board_issues - Get board issues with advanced filtering options

Issue Tools

• get_my_issues_grouped ⚡️ NEW & OPTIMIZED - Get your open issues grouped by status in a single request (5-6x faster than alternatives)
• search_issues - Search issues using JQL with flexible parameters
• get_issue_details - Get comprehensive issue information
• create_issue - Create new issues with full field support
• update_issue - Update existing issues
• transition_issue - Move issues between statuses
• add_comment - Add comments with rich text support
• complete_issue - Close/complete issues with AI-generated resolution and workflow handling

User Tools

• get_current_user - Get authenticated user information
• search_users - Find users by name, email, or username
• get_user_details - Get detailed user information

Project Tools

• get_projects - List all accessible projects
• get_project_details - Get comprehensive project information

Time Tracking Tools

• add_worklog - Log work time with flexible formats
• get_worklogs - View work logs for issues

System Tools

• get_server_info - Get server status and information

💡 Usage Examples

Natural Language Commands with Claude or Cursor

Once configured with Claude Desktop or Cursor, you can use natural language commands:

"Show me all my open issues in high priority"
"Create a new bug in PROJECT-X about login issues"
"Move ticket ABC-123 to In Progress"
"Log 2 hours of work on ABC-456 for code review"
"Add a comment to ABC-789 saying the fix is deployed"
"Show me all Scrum boards for the mobile project"
"Get details for issue ABC-100 including comments and worklogs"
"List all projects I have access to"
"Close issue ABC-123" or "Complete ABC-123"

⚡️ Optimized Issue Viewing (Recommended)

For the best performance when viewing your tasks, use the optimized grouped view:

# In Claude or Cursor
"/jira"  # Shows all your open issues grouped by status

# This uses get_my_issues_grouped which:
# - Makes only 1 API request (vs 6+ with traditional methods)
# - Groups issues by status automatically
# - Provides direct links to Jira
# - Shows quick action menu
# - 5-6x faster response time

For detailed setup instructions in Cursor, see:

• Quick Start: CURSOR_QUICK_START.md
• Full Prompt: CURSOR_JIRA_PROMPT.md

Using with MCP Inspector

# List all boards
npx @modelcontextprotocol/inspector \
  npx @orengrinker/jira-mcp-server \
  get_boards

# Search for your issues
npx @modelcontextprotocol/inspector \
  npx @orengrinker/jira-mcp-server \
  search_issues \
  '{"jql": "assignee=currentUser() AND status!=Done"}'

# Create a new issue
npx @modelcontextprotocol/inspector \
  npx @orengrinker/jira-mcp-server \
  create_issue \
  '{"projectKey": "PROJ", "issueType": "Task", "summary": "New task from MCP"}'

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()

# Unassigned issues in current sprint
assignee is EMPTY AND sprint in openSprints()

# Issues updated in the last 24 hours
updated >= -1d

# Epic issues with their child stories
"Epic Link" = PROJ-123 OR parent = PROJ-123

🔧 Configuration

Getting Your Jira API Token

1. Go to Atlassian Account Settings
2. Click "Create API token"
3. Give it a descriptive name (e.g., "MCP Server")
4. Copy the generated token
5. Use it in your environment variables

Permissions Required

Your Jira user should have:

• Browse projects permission
• Create issues permission (for issue creation)
• Edit issues permission (for updates and transitions)
• Work on issues permission (for worklogs)
• Add comments permission

🏗️ Development

Setup

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

Development 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
npm run test         # Run tests (when available)

Project Structure

src/
├── index.ts              # Main server entry point
├── jiraApiClient.ts      # Enhanced API client
├── toolRegistry.ts       # Tool registration and routing
├── types/
│   └── index.ts         # TypeScript type definitions
├── services/
│   ├── index.ts         # Service exports
│   ├── 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

1. Authentication Failed

   • Verify your API token and email are correct
   • Check that your Jira base URL is correct (should end with .atlassian.net for cloud)
   • Ensure your API token hasn't expired

2. Permission Denied

   • Verify your Jira user has the required permissions
   • Check project-level permissions for specific operations

3. Network Errors

   • Verify your Jira base URL is accessible
   • Check firewall and proxy settings
   • Ensure you're using HTTPS

4. Rate Limiting

   • The server includes built-in rate limiting
   • If you hit Jira's rate limits, wait and retry
   • Consider reducing concurrent requests

Debug Mode

DEBUG logging is enabled by default to help diagnose issues. The logs show:

• All Jira API requests (URL, method, parameters)
• Response status and summary (total items, counts)
• MCP tool execution (arguments, result preview)
• Error traces and detailed messages

To change log level, set environment variable:

export LOG_LEVEL=DEBUG  # DEBUG, INFO, WARN, ERROR (default: DEBUG)

MCP Server Logs

When running the MCP server through Cursor, you can find the logs here:

macOS:

# View live MCP logs with DEBUG output
tail -f ~/Library/Application\ Support/Cursor/logs/*/window*/exthost/anysphere.cursor-mcp/MCP\ user-jira.log

# Or list all log directories
ls -lt ~/Library/Application\ Support/Cursor/logs/

Windows:

%APPDATA%\Cursor\logs\

Linux:

~/.config/Cursor/logs/

Example DEBUG output:

[DEBUG] [JiraApiClient] Making GET request to: https://job.sbertroika.ru/rest/api/2/search?jql=...
[DEBUG] [JiraApiClient] Response status: 200 OK
[DEBUG] [JiraApiClient] Response summary: { total: 176, issuesCount: 176 }
[DEBUG] [JiraMCPServer] MCP result sent to Cursor: { type: 'text', textLength: 15521 }

The logs include:

• Connection status and authentication details
• API requests with full URLs and parameters
• API responses with status codes and data summaries
• MCP protocol messages and tool execution flow
• Error traces with detailed context

🧪 Testing

Using Make Commands

The project includes a comprehensive Makefile for easy testing:

# Show all available commands
make help

# Run all tests
make test-all

# Test specific functionality
make test-grouped          # Test get_my_issues_grouped (preview)
make test-grouped-full     # Test get_my_issues_grouped (full output)
make test-priorities       # Check Jira priorities
make test-current-user     # Get current user info
make test-my-issues        # Test search_issues

# Test specific issue
make test-issue-detail ISSUE_KEY=RIVER-123

# Test user search
make test-search-users QUERY=Агафонов

# View logs
make logs                  # Real-time log viewing
make logs-errors           # Show only errors

# Development
make build                 # Build project
make lint                  # Run linter
make format                # Format code
make typecheck             # Type checking

Manual Testing

# Test the server connection
JIRA_BASE_URL=https://your-company.atlassian.net \
JIRA_EMAIL=your@email.com \
JIRA_API_TOKEN=your-token \
node dist/index.js

🤝 Contributing

We welcome contributions! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes following our coding standards
4. Add tests for new functionality
5. Run the build: npm run build
6. Commit changes: git commit -m 'Add amazing feature'
7. Push to branch: git push origin feature/amazing-feature
8. Open a Pull Request

Coding Standards

• Follow TypeScript best practices
• Use meaningful variable and function names
• Add JSDoc comments for public APIs
• Follow conventional commit messages
• Ensure all builds pass

📊 Performance

• ⚡️ Optimized Issue Retrieval: New get_my_issues_grouped function reduces API calls from 6 to 1 (5-6x faster)
• Rate Limiting: Built-in rate limiting respects Jira API limits
• Connection Pooling: Efficient HTTP connection management
• Error Recovery: Automatic retry logic for transient failures
• Memory Efficient: Streaming responses for large datasets

Performance Comparison

Operation	Traditional Method	Optimized Method	Improvement
View my tasks	6 requests (~3-5s)	1 request (~0.5-1s)	5-6x faster ⚡️
View task details	1 request	1 request	Same
Complete task	1-3 requests	1-3 requests (auto-workflow)	Same + AI resolution

🔐 Security

• No Credential Storage: Uses environment variables only
• Input Validation: All inputs are validated and sanitized
• Secure Defaults: Follows security best practices
• Audit Trail: Comprehensive logging for debugging

📄 License

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

🔗 Links

• GitHub Repository: https://github.com/OrenGrinker/jira-mcp-server
• NPM Package: @orengrinker/jira-mcp-server
• Jira Cloud REST API: Documentation
• Model Context Protocol: Specification
• Create API Tokens: Atlassian Guide

🆘 Support

• Issues: GitHub Issues
• Documentation: Check this README and inline code documentation
• Feature Requests: Open an issue with the "enhancement" label

🏆 Acknowledgments

• Built with the Model Context Protocol SDK
• Inspired by the MCP community and best practices
• Thanks to all contributors and users providing feedback