# Jira MCP Server

A Model Context Protocol (MCP) server that provides comprehensive integration with Jira. This server enables AI assistants to interact with Jira through a standardized interface, allowing them to search, create, update, and manage Jira issues programmatically.

## Features

This MCP server provides the following tools for Jira integration:

- **🔍 Search Issues** - Search for issues using JQL (Jira Query Language)
- **📄 Get Issue Details** - Retrieve detailed information about specific issues
- **➕ Create Issues** - Create new issues in any project
- **✏️ Update Issues** - Modify existing issue fields
- **💬 Add Comments** - Add comments to issues
- **🔄 Get Transitions** - View available status transitions
- **⚡ Transition Issues** - Change issue status/workflow state
- **👤 Assign Issues** - Assign issues to users
- **📋 List Projects** - Get all accessible projects
- **🔎 Search Users** - Find users by name or email
- **📝 Get Comments** - Retrieve all comments from an issue
- **📊 Get Boards** - List all accessible Scrum and Kanban boards
- **📈 Get Board Issues** - Retrieve issues from a specific board

## Prerequisites

Before you begin, ensure you have:

- Node.js 18 or higher installed
- A Jira account (Cloud or Data Center)
- Jira API credentials (email and API token)
- Claude Desktop or another MCP-compatible client

## Installation

### 1. Clone or Download

```bash
git clone <repository-url>
cd jira-mcp
```

Or if you're starting from scratch in this directory, the files are already created.

### 2. Install Dependencies

```bash
npm install
```

This will install:

- `@modelcontextprotocol/sdk` - MCP SDK for building servers
- `axios` - HTTP client for Jira API calls
- `dotenv` - Environment variable management
- TypeScript and Node.js type definitions

### 3. Build the Project

```bash
npm run build
```

This compiles the TypeScript code to JavaScript in the `build/` directory.

## Configuration

### Step 1: Get Your Jira API Token

1. Log in to your Jira account at `https://your-domain.atlassian.net`
2. Go to **Account Settings** → **Security** → **API tokens**
3. Click **Create API token**
4. Give it a label (e.g., "MCP Server") and click **Create**
5. **Copy the token immediately** (you won't be able to see it again)

### Step 2: Create Environment File

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

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

**Important Notes:**

- `JIRA_HOST` should be just the domain without `https://`
- Use the email associated with your Jira account
- Keep your API token secure and never commit it to version control

### Step 3: Configure Claude Desktop

Add the server to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/jira-mcp/build/index.js"],
      "env": {
        "JIRA_HOST": "your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token-here"
      }
    }
  }
}
```

**Replace** `/ABSOLUTE/PATH/TO/jira-mcp` with the actual absolute path to your project directory.

### Step 4: Restart Claude Desktop

Completely quit and restart Claude Desktop for the changes to take effect.

## Usage

Once configured, you can ask Claude to interact with Jira using natural language. Here are some examples:

### Example Queries

#### Search for Issues

```
"Find all open bugs in the PROJ project"
"Show me issues assigned to me that are in progress"
"Search for issues created this week with high priority"
```

Behind the scenes, Claude will use JQL like:

- `project = PROJ AND type = Bug AND status = Open`
- `assignee = currentUser() AND status = "In Progress"`
- `created >= -1w AND priority = High`

#### Get Issue Details

```
"Show me the details of issue PROJ-123"
"What's the status of PROJ-456?"
```

#### Create New Issues

```
"Create a new bug in project PROJ with summary 'Login page not loading' and description 'Users cannot access the login page'"
"Create a task in PROJ called 'Update documentation' with high priority"
```

#### Update Issues

```
"Update PROJ-123 to change the summary to 'Fix login page loading issue'"
"Change the priority of PROJ-456 to High"
```

#### Add Comments

```
"Add a comment to PROJ-123 saying 'This has been fixed in the latest release'"
"Comment on PROJ-456: 'Waiting for QA team to verify'"
```

#### Transition Issues

```
"Move PROJ-123 to In Progress"
"Close PROJ-456"
```

For transitions, Claude will first get available transitions using `jira_get_transitions`, then execute the appropriate one.

#### Assign Issues

```
"Assign PROJ-123 to john.doe@example.com"
"Unassign PROJ-456"
```

You'll need the user's account ID, which Claude can find using `jira_search_users`.

#### List Projects

```
"What Jira projects do I have access to?"
"Show me all available projects"
```

#### Search Users

```
"Find user john.doe"
"Search for users named Smith"
```

#### Get Boards

```
"Show me all available boards"
"List all Scrum boards"
"What boards do I have access to?"
```

#### Get Board Issues

```
"Show me all issues from board 123"
"Get all stories from the development board"
"List issues from board 456 that are in progress"
```

## Available Tools Reference

### jira_search_issues

Search for issues using JQL.

**Parameters:**

- `jql` (required): JQL query string
- `maxResults` (optional): Maximum results (default: 50)
- `startAt` (optional): Starting index (default: 0)

**Example:**

```json
{
  "jql": "project = PROJ AND status = Open",
  "maxResults": 10
}
```

### jira_get_issue

Get detailed information about an issue.

**Parameters:**

- `issueKey` (required): Issue key (e.g., "PROJ-123")

**Example:**

```json
{
  "issueKey": "PROJ-123"
}
```

### jira_create_issue

Create a new issue.

**Parameters:**

- `projectKey` (required): Project key
- `summary` (required): Issue summary
- `issueType` (required): Issue type (Bug, Task, Story, etc.)
- `description` (optional): Issue description
- `priority` (optional): Priority (High, Medium, Low, etc.)

**Example:**

```json
{
  "projectKey": "PROJ",
  "summary": "Fix login bug",
  "issueType": "Bug",
  "description": "Login page not loading",
  "priority": "High"
}
```

### jira_update_issue

Update an existing issue.

**Parameters:**

- `issueKey` (required): Issue key
- `summary` (optional): Updated summary
- `description` (optional): Updated description
- `priority` (optional): Updated priority

**Example:**

```json
{
  "issueKey": "PROJ-123",
  "summary": "Updated summary",
  "priority": "High"
}
```

### jira_add_comment

Add a comment to an issue.

**Parameters:**

- `issueKey` (required): Issue key
- `comment` (required): Comment text

**Example:**

```json
{
  "issueKey": "PROJ-123",
  "comment": "This has been fixed"
}
```

### jira_get_transitions

Get available transitions for an issue.

**Parameters:**

- `issueKey` (required): Issue key

**Example:**

```json
{
  "issueKey": "PROJ-123"
}
```

### jira_transition_issue

Transition an issue to a new status.

**Parameters:**

- `issueKey` (required): Issue key
- `transitionId` (required): Transition ID (from get_transitions)

**Example:**

```json
{
  "issueKey": "PROJ-123",
  "transitionId": "31"
}
```

### jira_assign_issue

Assign an issue to a user.

**Parameters:**

- `issueKey` (required): Issue key
- `accountId` (required): User account ID (use null to unassign)

**Example:**

```json
{
  "issueKey": "PROJ-123",
  "accountId": "5d123456789abc0def123456"
}
```

### jira_get_projects

Get all accessible projects. No parameters required.

### jira_search_users

Search for users.

**Parameters:**

- `query` (required): Search query (name or email)

**Example:**

```json
{
  "query": "john.doe"
}
```

### jira_get_comments

Get all comments from an issue.

**Parameters:**

- `issueKey` (required): Issue key

**Example:**

```json
{
  "issueKey": "PROJ-123"
}
```

### jira_get_boards

Get a list of all accessible Jira boards (Scrum and Kanban).

**Parameters:**

- `startAt` (optional): Starting index (default: 0)
- `maxResults` (optional): Maximum results (default: 50)

**Example:**

```json
{
  "startAt": 0,
  "maxResults": 50
}
```

### jira_get_board_issues

Get issues from a specific Jira board. Useful for retrieving stories, tasks, and bugs from a board.

**Parameters:**

- `boardId` (required): Board ID number
- `startAt` (optional): Starting index (default: 0)
- `maxResults` (optional): Maximum results (default: 50)
- `jql` (optional): JQL filter to apply to board issues

**Example:**

```json
{
  "boardId": 123,
  "jql": "type = Story AND status = 'In Progress'",
  "maxResults": 20
}
```

## Development

### Project Structure

```
jira-mcp/
├── src/
│   ├── index.ts          # Main MCP server implementation
│   └── jira-client.ts    # Jira API client wrapper
├── build/                # Compiled JavaScript (generated)
├── package.json          # Project dependencies
├── tsconfig.json         # TypeScript configuration
├── .env                  # Environment variables (create this)
├── .gitignore           # Git ignore rules
└── README.md            # This file
```

### Available Scripts

- `npm run build` - Compile TypeScript to JavaScript
- `npm run watch` - Watch mode for development
- `npm run dev` - Run with Node.js debugger

### Making Changes

1. Edit TypeScript files in `src/`
2. Run `npm run build` to compile
3. Restart Claude Desktop to test changes

## Troubleshooting

### Server Not Appearing in Claude

1. Check that the path in `claude_desktop_config.json` is absolute and correct
2. Verify the `build/index.js` file exists (run `npm run build`)
3. Completely quit and restart Claude Desktop (not just close the window)
4. Check Claude Desktop logs for errors

### Authentication Errors

- Verify your `JIRA_HOST` doesn't include `https://`
- Confirm your API token is valid and hasn't expired
- Ensure the email matches your Jira account
- Check that your account has permission to access the Jira instance

### API Errors

- Check that project keys and issue keys are correct (case-sensitive)
- Verify you have permission to perform the operation
- Some operations may require specific Jira permissions
- Review the error message returned by the tool

### JQL Query Issues

- Test your JQL in Jira's search interface first
- Ensure field names are correct and quoted if they contain spaces
- Use proper JQL operators (=, !=, IN, NOT IN, etc.)
- Common fields: `project`, `status`, `assignee`, `priority`, `type`, `created`, `updated`

## Security Notes

- Never commit your `.env` file or API tokens
- API tokens have the same permissions as your user account
- Consider creating a dedicated service account for automation
- Regularly rotate your API tokens
- Use environment variables for all sensitive data

## JQL Reference

Common JQL examples:

```jql
# Issues in a project
project = PROJ

# Open bugs
project = PROJ AND type = Bug AND status = Open

# Assigned to me
assignee = currentUser()

# High priority issues
priority = High

# Created recently
created >= -7d

# Multiple conditions
project = PROJ AND status IN (Open, "In Progress") AND assignee = currentUser()
```

## API Rate Limits

Jira Cloud has rate limits:

- 10 requests per second per user
- Consider implementing delays for bulk operations
- The server handles individual requests; batch operations may hit limits

## License

MIT

## Support

For issues and questions:

- Check the troubleshooting section above
- Review Jira API documentation: https://developer.atlassian.com/cloud/jira/platform/rest/v3/
- Review MCP documentation: https://modelcontextprotocol.io

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

---

**Note**: This is an unofficial tool and is not affiliated with or endorsed by Atlassian.