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.

🚀 Quick Start

📦 Installation

npm install

⚙️ 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

🔑 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

▶️ Build and Run

npm run build
npm start

✨ Features

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

📋 System Requirements

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

💻 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"
}

🛠️ 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

⚙️ Configuration for Claude Desktop

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

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