# jira-mcp-server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that lets AI assistants create, search, and manage Jira issues. Authenticates using Chrome browser cookies, so it works seamlessly with SSO-protected Jira Cloud instances -- no API tokens needed.

## How it works

Instead of requiring a Jira API token, this server extracts session cookies from your Chrome browser. If you're logged into Jira in Chrome, the server can make API calls using your existing session. This is especially useful for organizations that use SSO (Azure AD, Okta, etc.) where generating long-lived API tokens isn't practical.

## Prerequisites

- **Node.js** 18+
- **Google Chrome** (or Chromium) on Linux
- An active Jira Cloud session in Chrome (log in before using)
- Chrome must not be running, or its cookie database must be unlockable

## Quick start

```bash
git clone https://github.com/chaholl/jira-mcp-server.git
cd jira-mcp-server
npm install
npm run build
npm run setup   # interactive wizard -- discovers your Jira instance config
```

The setup wizard will:

1. Ask for your Jira base URL and project key
2. Verify authentication via Chrome cookies
3. Auto-discover issue types, priorities, and custom fields from your Jira instance
4. Write a `jira-config.json` file (gitignored)

## MCP tools

| Tool | Description |
|------|-------------|
| `jira_auth_check` | Verify authentication and display the current user |
| `jira_create_issue` | Create a new issue (story, bug, task, etc.) |
| `jira_get_issue` | Fetch and display an issue by key |
| `jira_edit_description` | Update an issue's description |
| `jira_edit_acceptance_criteria` | Update the acceptance criteria field |
| `jira_add_comment` | Add a comment to an issue |
| `jira_transition_issue` | Move an issue to a new status |
| `jira_search` | Search issues using JQL |
| `jira_lookup_user` | Look up a user's account ID by email |
| `jira_list_components` | List available project components |
| `jira_reassign_issue` | Reassign an issue to a different user |
| `jira_reparent_issue` | Change an issue's parent (epic/story) |

## Configuration

### Setup wizard (recommended)

```bash
npm run setup
```

This interactively discovers your Jira instance's issue types, priorities, and custom fields, then writes `jira-config.json`.

### Manual configuration

Alternatively, set environment variables:

```bash
export JIRA_BASE_URL="https://your-org.atlassian.net"
export JIRA_PROJECT_KEY="MYPROJECT"
```

Or create `jira-config.json` in the project root:

```json
{
  "jiraBaseUrl": "https://your-org.atlassian.net",
  "projectKey": "MYPROJECT",
  "issueTypes": {
    "story": "10001",
    "bug": "10004",
    "task": "10002"
  },
  "priorities": {
    "critical": "1",
    "high": "2",
    "medium": "3",
    "low": "4"
  },
  "customFields": {
    "acceptance_criteria": "customfield_11083"
  }
}
```

## Adding to your MCP client

### Claude Code

```bash
claude mcp add jira -- node /path/to/jira-mcp-server/dist/index.js
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jira-mcp-server/dist/index.js"]
    }
  }
}
```

## Limitations

- **Linux only** -- Chrome cookie extraction uses Linux-specific paths and `secret-tool` for keyring access
- **Chrome/Chromium only** -- does not support Firefox, Safari, or other browsers
- **Session-based** -- if your Jira session expires in Chrome, you'll need to log in again
- **Single project** -- configured for one Jira project at a time

## License

MIT