Jira MCP Server

An MCP (Model Context Protocol) server for creating and fetching Jira issues via the REST API. Built with Bun.

Features

• Fetch and update existing Jira issues
• Create Jira issues with a single tool call
• Support for all standard issue fields (summary, description, type, priority, labels)
• Flexible description input:
  • Plain text → automatic conversion to basic ADF paragraphs
  • Pre-formatted ADF objects → full control over formatting (panels, headings, lists, etc.)
• Runtime ADF validation with Zod schemas
• Standalone executable (no runtime dependencies)
• --help flag for quick setup reference

Prerequisites

• Bun v1.0+ — install with curl -fsSL https://bun.sh/install | bash
  • Or use devbox for an isolated environment without a permanent Bun installation (see below)
• A Jira Cloud instance
• Jira API token (see Atlassian API tokens)

Installation

git clone <your-repo-url>
cd jira-mcp-server
bun install

Using devbox (no permanent Bun installation)

If you prefer not to install Bun globally, devbox provides an isolated shell with Bun available:

# Install devbox (one-time)
curl -fsSL https://get.jetify.com/devbox | bash

# Enter the devbox shell (installs Bun automatically)
devbox shell

# Now use bun as normal
bun install
bun run build

Run exit to leave the devbox shell. Bun is not added to your system outside of it.

Configuration

The server requires these environment variables:

Variable	Description	Example
JIRA_URL	Your Jira instance URL	https://your-domain.atlassian.net
JIRA_EMAIL	Your Jira account email	user@example.com
JIRA_API_TOKEN	Your Jira API token	your-api-token
JIRA_PROJECT	Default project key for issue creation	PROJ

Usage

# Build standalone executable
bun run build

# Build and deploy to ~/bin
bun run deploy

# Build, deploy, and sign (required on macOS — see note below)
bun run deploy-and-sign

# Run from source (development)
bun run dev

# Inspect with MCP Inspector
bun run mcp-inspect

# Display setup instructions
./dist/jira-mcp-server --help

macOS: use deploy-and-sign

On macOS, use bun run deploy-and-sign instead of bun run deploy. When bun build --compile produces a binary, it embeds a code signature. Copying the file with cp invalidates that signature because macOS recalculates file hashes on copy. Gatekeeper then kills the binary with SIGKILL when you try to run it from the new location.

deploy-and-sign adds an ad-hoc re-signing step (codesign -s -) after the copy, which satisfies macOS without requiring an Apple Developer certificate.

Integration with MCP Clients

Claude Desktop

Add to your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "jira": {
      "command": "/absolute/path/to/jira-mcp-server/dist/jira-mcp-server",
      "env": {
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "user@example.com",
        "JIRA_API_TOKEN": "your-token",
        "JIRA_PROJECT": "PROJ"
      }
    }
  }
}

For development (running from source), replace command with "bun" and add "args": ["run", "/absolute/path/to/jira-mcp-server/src/index.ts"].

Cursor

1. Open Cursor Settings → Features → MCP
2. Add a new MCP server:
   • Transport type: stdio
   • Command: /absolute/path/to/jira-mcp-server/dist/jira-mcp-server
3. Set the environment variables in Cursor's settings

Claude Code

claude mcp add jira /absolute/path/to/jira-mcp-server/dist/jira-mcp-server

Tool Reference

jira-search-issues

Searches for Jira issues using a JQL query. Returns a list of matching issues with key fields.

Parameter	Type	Required	Description
jql	string	Yes	JQL query string
maxResults	number	No	Maximum results to return (1–100, default 20)

JQL examples:

project = MYPROJ AND status = "In Progress"
assignee = currentUser() AND sprint in openSprints()
project = MYPROJ AND labels = "backend" ORDER BY created DESC

Example response:

{
  "success": true,
  "total": 42,
  "returned": 20,
  "issues": [
    {
      "key": "PROJ-123",
      "summary": "Fix login button on mobile",
      "status": "In Progress",
      "priority": "High",
      "issueType": "Bug",
      "assignee": "Jane Doe",
      "reporter": "John Smith",
      "labels": ["mobile", "frontend"],
      "created": "2026-02-19T10:00:00.000+0000",
      "updated": "2026-02-19T12:30:00.000+0000",
      "url": "https://your-domain.atlassian.net/browse/PROJ-123"
    }
  ]
}

jira-get-issue

Fetches an existing Jira issue by its key.

Parameter	Type	Required	Description
issueKey	string	Yes	The issue key (e.g. "PROJ-123")

Example response:

{
  "success": true,
  "issue": {
    "key": "PROJ-123",
    "summary": "Fix login button on mobile",
    "status": "In Progress",
    "priority": "High",
    "issueType": "Bug",
    "assignee": "Jane Doe",
    "reporter": "John Smith",
    "labels": ["mobile", "frontend"],
    "description": { "type": "doc", "version": 1, "content": [] },
    "created": "2026-02-19T10:00:00.000+0000",
    "updated": "2026-02-19T12:30:00.000+0000",
    "url": "https://your-domain.atlassian.net/browse/PROJ-123"
  }
}

jira-update-issue

Updates an existing Jira issue's summary and/or description. At least one field must be provided.

Parameter	Type	Required	Description
issueKey	string	Yes	The issue key (e.g. "PROJ-123")
summary	string	No	New summary/title for the issue
description	string or ADF	No	Plain text or pre-formatted ADF

Example response:

{
  "success": true,
  "issue": {
    "key": "PROJ-123",
    "url": "https://your-domain.atlassian.net/browse/PROJ-123"
  },
  "message": "Successfully updated issue PROJ-123"
}

jira-create-issue

Creates a new issue in Jira.

Parameter	Type	Required	Description
summary	string	Yes	Summary/title of the issue
description	string or ADF	No	Plain text or pre-formatted ADF object
issueType	string	No	Issue type (default: "Task")
priority	string	No	Priority level ("Highest", "High", "Medium", "Low", "Lowest")
labels	string[]	No	Labels to add to the issue
projectKey	string	No	Override the default project key
parentKey	string	No	Parent issue key (e.g. "PROJ-10") — creates as a child issue

Description formatting:

Plain text is converted to ADF paragraphs automatically:

"description": "Main description.\n\nAnother paragraph."

For full formatting control, pass a pre-formatted ADF object:

"description": {
  "type": "doc",
  "version": 1,
  "content": [
    { "type": "paragraph", "content": [{ "type": "text", "text": "Main description" }] },
    { "type": "heading", "attrs": { "level": 3 }, "content": [{ "type": "text", "text": "TODO" }] },
    { "type": "panel", "attrs": { "panelType": "error" }, "content": [
      { "type": "paragraph", "content": [{ "type": "text", "text": "First task" }] }
    ]}
  ]
}

Panel types: error (red), info (blue), warning (yellow), success (green), note (purple).

Example response:

{
  "success": true,
  "issue": {
    "id": "10001",
    "key": "PROJ-123",
    "url": "https://your-domain.atlassian.net/browse/PROJ-123"
  },
  "message": "Successfully created issue PROJ-123"
}

Example Commands

jira-ticket

An interactive command for drafting and creating Jira tickets with proper ADF formatting. Supports Stories, Bugs, and Maintenance tasks with a smart question flow and automatic ADF construction.

Location: command/jira-ticket.md

/jira-ticket [optional summary]

Project Structure

jira-mcp-server/
├── src/
│   ├── index.ts           # Entry point, orchestrates startup
│   ├── config.ts          # Environment variable validation
│   ├── server.ts          # MCP server setup and tool registration
│   ├── jira-client.ts     # Jira REST API client
│   ├── adf-schema.ts      # Zod schema for ADF validation
│   ├── adf-schema.test.ts # ADF validation tests
│   ├── types.ts           # TypeScript type definitions
│   ├── help.ts            # Help text display
│   └── version.ts         # Version from package.json
├── dist/
│   └── jira-mcp-server    # Standalone executable (after build)
├── command/
│   └── jira-ticket.md     # Interactive ticket creation command
├── biome.json             # Linter/formatter configuration
└── package.json

Available Scripts

Script	Description
build	Build standalone executable with Bun runtime included
deploy	Build and copy executable to ~/bin directory
deploy-and-sign	Build, copy, and ad-hoc sign (required on macOS)
dev	Run source directly with Bun (for development)
test	Run tests with Bun
lint	Check code with Biome (lint + format)
lint:fix	Auto-fix lint and format issues
mcp-inspect	Build and launch MCP Inspector for manual testing

Future Improvements

• [ ] Add more Jira operations (delete, search, comment, transitions)
• [ ] Support for custom fields
• [ ] Support for attachments
• [ ] Caching of project/issue type metadata
• [ ] Support for Jira Server/Data Center (different auth method)
• [ ] Add assignee field support
• [ ] Add component support

License

MIT