Jira MCP Server

🚀 Jira MCP Server

A Model Context Protocol (MCP) server for Jira integration, enabling AI assistants like Claude to interact with Jira Cloud instances.

✨ Features

• 🎫 Issue management (create, read, update, search)
• 📋 Project listing
• 🔍 JQL search capabilities
• 🔐 API token authentication
• 📝 TypeScript implementation
• 🖥️ Cross - platform support (Windows, macOS, Linux)

📦 Installation

System Requirements

• Node.js 18.x or higher
• npm or yarn
• Jira Cloud instance (does not work with Jira Server/Data Center)

Steps

1. Install dependencies:

npm install

2. Configuration: Create a .env file in the project root:

JIRA_HOST=your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-api-token-here

3. Generate API Token:
   1. Go to Atlassian Account Settings
   2. Click "Create API token"
   3. Give it a meaningful label
   4. Copy the token to your .env file
4. Build and Run:

npm run build
npm start

💻 Usage Examples

Basic Usage

Creating an Issue

{
  "projectKey": "PROJ",
  "summary": "Fix login bug",
  "description": "Users cannot log in with special characters in password",
  "issueType": "Bug"
}

Searching Issues

{
  "jql": "project = PROJ AND status = \"In Progress\" AND assignee = currentUser()",
  "maxResults": 20
}

Getting Issue Details

{
  "issueKey": "PROJ-123"
}

Advanced Usage

Configuration for Claude Desktop

Add this to your Claude Desktop MCP configuration:

macOS/Linux

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jira-mcp-server/build/index.js"],
      "env": {
        "JIRA_HOST": "your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Windows

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["C:\\path\\to\\jira-mcp-server\\build\\index.js"],
      "env": {
        "JIRA_HOST": "your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

📚 Documentation

Available Tools

Issue Management

• jira_create_issue - Create new issues
• jira_get_issue - Get detailed issue information
• jira_update_issue - Update issue fields
• jira_search_issues - Search issues using JQL
• jira_list_projects - List all accessible projects

Authentication

Uses Basic Authentication with email + API token. This is the most secure method for Jira Cloud.

Error Handling

The server includes comprehensive error handling for:

• Invalid credentials
• Network timeouts
• Invalid JQL queries
• Missing permissions
• Non-existent resources

All errors are returned in a structured format with helpful messages.

Development

Building

npm run build

Testing

# Test the server
node build/index.js

Troubleshooting

Common Issues

1. Server won't start:
   • Check your .env file is properly configured
   • Verify your API token is valid
   • Ensure Node.js version is 18+
2. Permission errors:
   • Verify your Jira user has appropriate permissions
   • Check that the project key exists and is accessible
3. Connection issues:
   • Verify your Jira host URL is correct
   • Check network connectivity to Jira Cloud

📄 License

ISC

🤝 Contributing

Please see CONTRIBUTING.md for details on how to contribute to this project.

🛠️ Support

For issues and feature requests, please use the GitHub issue tracker.