# Jira MCP Server

An MCP (Model Context Protocol) server for Jira integration. Connect your AI coding assistant to your Jira instance to search, create, update, and manage issues without leaving your editor.

## Features

- **12 tools** exposed via MCP stdio transport
- Auth via Jira API token (HTTP Basic)
- Search using the latest `/rest/api/3/search/jql` endpoint
- JSON Schema tool definitions (compatible with strict MCP clients)

### Available Tools

| Tool | Description | Read/Write |
|---|---|---|
| `get_issue` | Get a single issue by key | Read |
| `get_issues` | Search issues by project, board, or raw JQL | Read |
| `get_assigned_issues` | Get issues assigned to a user | Read |
| `create_issue` | Create a new issue | Write |
| `update_issue` | Update issue fields (summary, description, assignee, status, priority) | Write |
| `delete_issue` | Delete an issue (destructive) | Write |
| `create_issue_link` | Link two issues (Blocks, Relates to, etc.) | Write |
| `get_user` | Find a user by email | Read |
| `list_users` | List all Jira users (paginated) | Read |
| `list_fields` | List all available Jira fields | Read |
| `list_issue_types` | List all issue types (Bug, Task, Story, Epic) | Read |
| `list_link_types` | List all issue link types | Read |

---

## Prerequisites

- **Node.js 20+** (uses built-in `fetch`)
- A **Jira Cloud** account with an API token
- Your Jira site URL (e.g. `https://your-team.atlassian.net`)

### Create a Jira API Token

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click **Create API token**
3. Name it (e.g. "MCP Server")
4. Copy the token (starts with `ATATT3`)

---

## Setup

### 1. Clone and install

```bash
git clone <your-repo-url> jira-mcp
cd jira-mcp
npm install
```

### 2. Build

```bash
npm run build
```

### 3. Verify it works

```bash
npm run inspector
```

This launches the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) — a web UI for testing MCP tools directly. Or test from the command line:

```bash
npm start
```

You should see: `Jira MCP server running on stdio.`

> **Note:** The inspector and `npm start` commands require env vars to be available. You can pass them inline:
> ```bash
> JIRA_HOST=https://your-team.atlassian.net JIRA_EMAIL=you@example.com JIRA_API_TOKEN=ATATT3xF... npm start
> ```
> Or create a `.env` file (see below).

---

## Connect to your AI assistant

The server communicates over stdio. All clients use the same command:

```
node /absolute/path/to/jira-mcp/build/index.js
```

Replace `/absolute/path/to/jira-mcp` with the actual path to your cloned repo.

### Opencode

Edit `~/.config/opencode/opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "local",
      "command": ["node", "/absolute/path/to/jira-mcp/build/index.js"],
      "enabled": true,
      "timeout": 30000,
      "environment": {
        "JIRA_HOST": "https://your-team.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "ATATT3xF..."
      }
    }
  }
}
```

Restart opencode. Verify with:

```bash
opencode mcp list
```

### Claude Code

Edit `~/.claude/claude_desktop_config.json` (Claude Desktop) or `.claude/settings.json` (Claude Code CLI):

```json
{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/jira-mcp/build/index.js"],
      "env": {
        "JIRA_HOST": "https://your-team.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "ATATT3xF..."
      }
    }
  }
}
```

Restart Claude. Tools appear as `mcp__jira__get_issue`, `mcp__jira__create_issue`, etc.

### Codex CLI

Edit `~/.codex/config.toml`:

```toml
[mcp_servers.jira]
command = "node"
args = ["/absolute/path/to/jira-mcp/build/index.js"]
cwd = "/absolute/path/to/jira-mcp"
enabled = true
startup_timeout_sec = 30

[mcp_servers.jira.env]
JIRA_HOST = "https://your-team.atlassian.net"
JIRA_EMAIL = "your-email@example.com"
JIRA_API_TOKEN = "ATATT3xF..."
```

Restart Codex.

### Cursor

Edit `~/.cursor/mcp.json` (or `.cursor/mcp.json` in your project root):

```json
{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/jira-mcp/build/index.js"],
      "env": {
        "JIRA_HOST": "https://your-team.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "ATATT3xF..."
      }
    }
  }
}
```

Restart Cursor.

### VS Code (with Continue extension)

Edit `~/.continue/config.json` and add under `experimental.modelContextProtocolServers`:

```json
{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "node",
          "args": ["/absolute/path/to/jira-mcp/build/index.js"],
          "env": {
            "JIRA_HOST": "https://your-team.atlassian.net",
            "JIRA_EMAIL": "your-email@example.com",
            "JIRA_API_TOKEN": "ATATT3xF..."
          }
        }
      }
    ]
  }
}
```

Restart VS Code.

> **VS Code note:** As of mid-2026, native MCP support in VS Code is evolving. The Continue extension provides the most stable MCP integration. Check the [Continue docs](https://docs.continue.dev) for the latest config format if the above doesn't match your version.

---

## Environment variables

The server needs three variables. **You only need to provide them once** — either in your client config (recommended) or in a `.env` file. You do not need both.

### Option A — Client config (recommended)

Pass env vars directly in your client's MCP config via the `environment` / `env` block. This is shown in all the client examples above. No `.env` file needed.

### Option B — `.env` file (alternative)

If you prefer not to put credentials in each client's config, create a `.env` file in the repo root:

```bash
cp .env.example .env
```

Edit `.env`:

```env
JIRA_HOST=https://your-team.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=ATATT3xF...
```

The server loads `.env` via `dotenv.config()` at startup. If the client config also passes env vars, those take precedence.

> **Important:** 
> - `JIRA_HOST` must be your Jira site URL (e.g. `https://your-team.atlassian.net`), **not** an Atlassian org admin URL.
> - The API token authenticates via **HTTP Basic** (email + token), not Bearer. This is handled automatically by the server.
> - `.env` is gitignored — never commit your token.

### Variables

| Variable | Required | Example |
|---|---|---|
| `JIRA_HOST` | Yes | `https://your-team.atlassian.net` |
| `JIRA_EMAIL` | Yes | `your-email@example.com` |
| `JIRA_API_TOKEN` | Yes | `ATATT3xF...` (from Atlassian API token page) |

---

## Usage examples

Once connected, ask your AI assistant in natural language:

- "Get issue KAN-42"
- "Create a task called 'Fix login bug' in project KAN, assign to sadeq@example.com"
- "Show me all In Progress issues with High priority"
- "List all Jira users"
- "Find the user with email alice@example.com"
- "Update KAN-15 status to In Progress"
- "Link KAN-3 and KAN-7 with 'Blocks'"

The AI will call the appropriate MCP tool automatically.

---

## Development

```bash
# Watch mode (auto-rebuild on save)
npm run dev

# Typecheck only
npx tsc --noEmit

# Run inspector for interactive testing
npm run inspector
```

### Tech stack

- **Runtime:** Node.js 20+
- **MCP SDK:** `@modelcontextprotocol/sdk`
- **Jira client:** `jira.js` (v3) — with a custom `fetch` workaround for the deprecated search endpoint
- **Schema validation:** `zod` + `zod-to-json-schema` for MCP-compatible JSON Schema output
- **Language:** TypeScript (ESM)

### Known limitations

- The `searchForIssuesUsingJql` method in `jira.js` targets a deprecated Atlassian endpoint. We bypass it with a direct `fetch` to `/rest/api/3/search/jql`.
- `create_issue` and `update_issue` assign via `accountId` (not username) for Jira Cloud compatibility.
- No support yet for comments, worklogs, sprints, attachments, or watchers. See the open tasks in your Jira board for planned additions.

---

## Troubleshooting

| Problem | Cause | Fix |
|---|---|---|
| `JIRA_HOST, JIRA_EMAIL, and JIRA_API_TOKEN environment variables are required` | Env vars not loaded | Pass them in client config `environment`/`env` block, or create `.env` in the repo root |
| `server unavailable` / `failed to load` in client | Bad JSON Schema in `tools/list` | Rebuild with `npm run build` and restart the client |
| `The requested API has been removed` | Old jira.js search endpoint | Already fixed — ensure you're on the latest build |
| `assignee: null` after create/update | Using legacy `name` instead of `accountId` | Already fixed — ensure you're on the latest build |
| Connection works but tools don't appear | Client not restarted after config change | Fully quit and restart the client (config is loaded once at startup) |
| `JIRA_HOST` is an org URL, not a site URL | Wrong host format | Use `https://your-team.atlassian.net`, not `https://home.atlassian.com/o/...` |

---

## Security

- `.env` is gitignored — never commit your API token.
- If you store credentials in your client config (e.g. `opencode.json`, `config.toml`), ensure that file is also gitignored or stored outside version control.
- The Jira API token grants full access to your Jira account. Treat it like a password.