# Jira MCP Server

> An MCP server for [Jira](https://www.atlassian.com/software/jira) — connect any MCP-compatible client to your Jira projects, issues, sprints, and boards.

[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-blueviolet)](https://modelcontextprotocol.io)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

## What is this?

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that gives AI assistants and agents full access to your Jira instance — search issues with JQL, create and update tickets, manage sprints and boards, transition issues through workflows, and link related work — all through natural language.

Use it with **Claude Desktop**, **Cursor**, **Windsurf**, **Cline**, **Continue**, or any MCP-compatible client to manage your projects without leaving the chat.

## Why use this?

- **14 built-in tools** — covers search, CRUD, transitions, comments, projects, boards, sprints, and backlog
- **Full JQL support** — search issues with any Jira Query Language expression
- **Workflow transitions** — move issues through your custom workflows by name
- **Sprint management** — query sprint states, goals, and board backlogs
- **Works with Jira Cloud** — connects to any `*.atlassian.net` instance

## Quick Start

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "jira-mcp-server"],
      "env": {
        "JIRA_HOST": "your-domain.atlassian.net",
        "JIRA_EMAIL": "you@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

### Cursor / VS Code

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "jira-mcp-server"],
      "env": {
        "JIRA_HOST": "your-domain.atlassian.net",
        "JIRA_EMAIL": "you@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

### Manual

```bash
npm install -g jira-mcp-server
export JIRA_HOST=your-domain.atlassian.net
export JIRA_EMAIL=you@example.com
export JIRA_API_TOKEN=your-api-token
jira-mcp-server
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `JIRA_HOST` | Yes | Your Jira hostname (e.g. `your-domain.atlassian.net`) |
| `JIRA_API_TOKEN` | Yes | Jira API token or Personal Access Token |
| `JIRA_EMAIL` | Cond. | Your Jira email (required for Basic auth) |
| `JIRA_AUTH_TYPE` | No | `basic` (default) or `bearer` (for PAT) |
| `JIRA_API_VERSION` | No | REST API version (default: `3`) |

### Getting your API token

1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click **Create API token**
3. Give it a name (e.g. "MCP Server") and copy the token
4. Use your Atlassian email as `JIRA_EMAIL`

## Tools

| Tool | Description |
|------|-------------|
| `jira_search` | Search issues with JQL |
| `jira_get_issue` | Get full issue details |
| `jira_create_issue` | Create a new issue |
| `jira_update_issue` | Update issue fields |
| `jira_transition_issue` | Transition issue to new status |
| `jira_add_comment` | Add a comment to an issue |
| `jira_delete_issue` | Delete an issue (permanent) |
| `jira_list_projects` | List accessible projects |
| `jira_get_project` | Get project details |
| `jira_get_issue_types` | List issue types for a project |
| `jira_link_issues` | Create a link between two issues |
| `jira_get_boards` | List Jira Software boards |
| `jira_get_sprints` | List sprints for a board |
| `jira_get_backlog` | Get board backlog items |

## Usage Examples

### Search issues with JQL

```json
{ "tool": "jira_search", "arguments": { "jql": "project = PROJ AND status = Open ORDER BY created DESC" } }
```

### Create a bug

```json
{
  "tool": "jira_create_issue",
  "arguments": {
    "projectKey": "PROJ",
    "summary": "Login page broken on mobile",
    "issueType": "Bug",
    "priority": "High",
    "labels": "mobile,urgent"
  }
}
```

### Transition an issue

```json
{ "tool": "jira_transition_issue", "arguments": { "issueKey": "PROJ-123", "transitionName": "In Progress" } }
```

### Get sprint backlog

```json
{ "tool": "jira_get_backlog", "arguments": { "boardId": "42" } }
```

## Use Cases

- **Project management** — "Show me all open bugs in the mobile project" → `jira_search` with JQL
- **Sprint planning** — "What's in the current sprint?" → `jira_get_sprints` + `jira_get_backlog`
- **Issue triage** — "Create a bug for the login timeout" → `jira_create_issue`
- **Workflow automation** — "Move PROJ-456 to In Review" → `jira_transition_issue`
- **Cross-project overview** — "List all projects I have access to" → `jira_list_projects`

## API Coverage

| Resource | Tools |
|----------|-------|
| Issues | `jira_search`, `jira_get_issue`, `jira_create_issue`, `jira_update_issue`, `jira_transition_issue`, `jira_delete_issue` |
| Comments | `jira_add_comment` |
| Projects | `jira_list_projects`, `jira_get_project` |
| Issue Types | `jira_get_issue_types` |
| Links | `jira_link_issues` |
| Boards | `jira_get_boards` |
| Sprints | `jira_get_sprints` |
| Backlog | `jira_get_backlog` |

## Development

```bash
git clone https://github.com/friendlygeorge/jira-mcp-server.git
cd jira-mcp-server
npm install
npm run build
npm start
```

## License

MIT