# Jira MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-1.0-purple)](https://modelcontextprotocol.io)

<!-- Add these badges once published to GitHub/npm -->
<!-- ![GitHub stars](https://img.shields.io/github/stars/YOUR_USERNAME/jira-mcp-server?style=social) -->
<!-- ![GitHub forks](https://img.shields.io/github/forks/YOUR_USERNAME/jira-mcp-server?style=social) -->
<!-- ![GitHub issues](https://img.shields.io/github/issues/YOUR_USERNAME/jira-mcp-server) -->
<!-- ![GitHub pull requests](https://img.shields.io/github/issues-pr/YOUR_USERNAME/jira-mcp-server) -->
<!-- ![npm version](https://img.shields.io/npm/v/jira-mcp-server) -->
<!-- ![npm downloads](https://img.shields.io/npm/dm/jira-mcp-server) -->

A Model Context Protocol (MCP) server for self-hosted Jira instances using Personal Access Token (PAT) authentication.

## ✨ Features

- **Issue Management**: Get, create, update, delete, and assign issues
- **Search**: Search issues using JQL
- **Comments**: Get, add, update, and delete comments
- **Transitions**: Get available transitions and transition issues
- **Projects**: List and get project details
- **Users**: Search users and get current user
- **Watchers**: Add watchers to issues
- **Issue Links**: Link issues together

## 📋 Prerequisites

- Node.js 18+
- Self-hosted Jira instance (tested with v9.12.12)
- Personal Access Token (PAT) for authentication

## 🚀 Installation

```bash
npm install
npm run build
```

## ⚙️ Configuration

Create a `.env` file in the project root:

```env
JIRA_BASE_URL=https://your-jira-instance.com/
PAT=your-personal-access-token
```

### Getting a Personal Access Token

1. Log in to your Jira instance
2. Go to Profile → Personal Access Tokens
3. Create a new token with appropriate permissions
4. Copy the token to your `.env` file

## 📖 Usage

### Running the Server

```bash
npm start
```

### Development Mode

```bash
npm run dev
```

### Using with npx (Recommended)

No installation required! Add the following to your MCP configuration:

```json
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "jira-mcp-server-pro"],
      "env": {
        "JIRA_BASE_URL": "https://your-jira-instance.com/",
        "PAT": "your-personal-access-token"
      }
    }
  }
}
```

### Global Installation

```bash
npm install -g jira-mcp-server-pro
```

Then add to your MCP configuration:

```json
{
  "mcpServers": {
    "jira": {
      "command": "jira-mcp-server-pro",
      "env": {
        "JIRA_BASE_URL": "https://your-jira-instance.com/",
        "PAT": "your-personal-access-token"
      }
    }
  }
}
```

### Local Development

If running from source, add the following to your MCP configuration:

```json
{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jiraMCP/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://your-jira-instance.com/",
        "PAT": "your-personal-access-token"
      }
    }
  }
}
```

## 🛠️ Available Tools (27 total)

### Issue Operations

| Tool                         | Description                                                                   |
| ---------------------------- | ----------------------------------------------------------------------------- |
| `jira_get_issue`             | Get details of a Jira issue by its key                                        |
| `jira_search_issues`         | Search for issues using JQL                                                   |
| `jira_create_issue`          | Create a new issue (basic fields)                                             |
| `jira_create_issue_advanced` | Create issue with full field support (fixVersions, components, custom fields) |
| `jira_update_issue`          | Update an existing issue (basic fields)                                       |
| `jira_update_issue_advanced` | Update issue with full field support                                          |
| `jira_delete_issue`          | Delete an issue                                                               |
| `jira_assign_issue`          | Assign or unassign an issue                                                   |
| `jira_get_transitions`       | Get available transitions for an issue                                        |
| `jira_transition_issue`      | Transition an issue to a new status                                           |
| `jira_link_issues`           | Link two issues                                                               |
| `jira_add_watcher`           | Add a watcher to an issue                                                     |

### Comments

| Tool                | Description               |
| ------------------- | ------------------------- |
| `jira_get_comments` | Get comments on an issue  |
| `jira_add_comment`  | Add a comment to an issue |

### Projects

| Tool                          | Description                                      |
| ----------------------------- | ------------------------------------------------ |
| `jira_get_projects`           | Get all projects                                 |
| `jira_get_project`            | Get details of a specific project                |
| `jira_get_project_versions`   | Get all versions for a project (for fixVersions) |
| `jira_get_project_components` | Get all components for a project                 |

### Metadata & Field Discovery

| Tool                        | Description                                                               |
| --------------------------- | ------------------------------------------------------------------------- |
| `jira_get_create_meta`      | **IMPORTANT**: Get required fields and allowed values for creating issues |
| `jira_get_edit_meta`        | Get editable fields and allowed values for an existing issue              |
| `jira_get_fields`           | Get all available fields including custom fields                          |
| `jira_get_field_options`    | Get allowed values for a specific field                                   |
| `jira_get_priorities`       | Get all available priorities                                              |
| `jira_get_statuses`         | Get all available statuses                                                |
| `jira_get_issue_link_types` | Get all available issue link types                                        |

### Users

| Tool                    | Description                        |
| ----------------------- | ---------------------------------- |
| `jira_search_users`     | Search for users                   |
| `jira_get_current_user` | Get the current authenticated user |

## 📝 Workflow: Creating Issues with Required Fields

1. **First**, call `jira_get_create_meta` to discover required fields and allowed values:

   ```
   jira_get_create_meta(projectKey: "PROJ", issueType: "Bug")
   ```

   This returns all fields with their requirements and dropdown options.

2. **Then**, use `jira_create_issue_advanced` with the correct values:
   ```
   jira_create_issue_advanced(
     projectKey: "PROJ",
     summary: "Issue title",
     issueType: "Bug",
     fixVersions: ["1.0.0"],
     components: ["Backend"],
     customFields: {"customfield_10001": "value"}
   )
   ```

## 📚 Resources

The server exposes MCP Resources for quick access to Jira data without tool calls:

| Resource URI           | Description                                            |
| ---------------------- | ------------------------------------------------------ |
| `jira://config`        | Server configuration and connection info               |
| `jira://current-user`  | Currently authenticated user details                   |
| `jira://priorities`    | All available issue priorities                         |
| `jira://statuses`      | All available issue statuses                           |
| `jira://fields`        | All fields (system + custom) grouped by type           |
| `jira://link-types`    | Available issue link types                             |
| `jira://projects`      | List of all projects (key, name, type)                 |
| `jira://project/{KEY}` | Project details with versions, components, issue types |
| `jira://my-issues`     | Issues assigned to current user                        |

### Using Resources

Resources provide context without explicit tool calls. For example, reading `jira://project/MSSP` returns:

```json
{
  "key": "MSSP",
  "name": "MSSP",
  "versions": [{"name": "1.0.0", "released": true}, ...],
  "components": [{"name": "LOGIN"}, {"name": "MSSP-FO"}, ...],
  "issueTypes": [{"id": "1", "name": "Bug"}, {"id": "3", "name": "Task"}, ...]
}
```

## 🔍 Example JQL Queries

```
# Issues assigned to me
assignee = currentUser()

# Open bugs in a project
project = PROJ AND issuetype = Bug AND status != Done

# Issues created in the last 7 days
created >= -7d

# High priority issues
priority in (Highest, High)
```

## 🤝 Contributing

Contributions are welcome! Here's how you can help:

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

### Development Setup

```bash
# Clone your fork
git clone https://github.com/YOUR_USERNAME/jira-mcp-server.git
cd jira-mcp-server

# Install dependencies
npm install

# Run in development mode
npm run dev
```

### Reporting Issues

- Use the [GitHub Issues](https://github.com/YOUR_USERNAME/jira-mcp-server/issues) to report bugs
- Include your Node.js version, Jira version, and steps to reproduce
- Check existing issues before creating a new one

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io) for the MCP specification
- [Atlassian](https://www.atlassian.com/) for Jira REST API documentation

---

<p align="center">
  Made with ❤️ for the MCP community
</p>