jira-run-mcp

An internal MCP (Model Context Protocol) server for Jira 8, using SSO session bootstrap via Playwright and HTTP-first tool execution. Uses stdio transport — runs as a local subprocess managed by Claude Desktop, Cursor, or any MCP-compatible client.

Stack

• TypeScript — strict, ESM (NodeNext)

• @modelcontextprotocol/sdk — MCP server + stdio transport

• Playwright — interactive SSO login and session persistence

• Zod — config and tool input validation

• Axios — Jira REST API HTTP client

Related MCP server: Jira MCP Server

Features

• 🔐 SSO authentication via Playwright (headed browser)

• 💾 Persistent local session (Playwright storage state / cookies)

• 🔍 jira_get_issue — fetch a single issue by key

• 🔎 jira_search_issues — execute JQL and return a compact issue list

• 🔎 jira_smart_search — search by issue key, JQL, or natural-language filters

• 🗓️ jira_daily_briefing — fixed Vietnamese project delivery briefing for managers

• ⏱️ jira_add_worklog — log work on a Jira issue through Tempo Timesheets

• 📝 jira_create_issue — create an issue using issue-type-specific required and optional fields

• 💬 jira_add_comment — add plain-text or ADF comments to an issue

• ✏️ jira_update_comment / jira_delete_comment — update or remove issue comments

• 🔄 jira_transition_issue — move an issue through workflow transitions by id or name

• 🧭 jira_get_create_meta — inspect static create metadata from src/jira/constants.ts

• 🧭 jira_get_edit_meta — inspect live editable fields for one issue

• ✏️ jira_update_issue_fields — update a curated set of Jira fields safely

• 🛡️ jira_validate_issue_update — validate update payloads without writing

• 🛡️ jira_bulk_update_issue_fields / jira_bulk_transition_issues — bulk operations with explicit dryRun

• 🛡️ jira_preview_create_issue — build create payloads without POSTing

• 🧾 jira_get_audit_context — compact issue audit context for LLM review

• 🔗 jira_link_issues — create links between issues

• 🔗 jira_get_issue_links / jira_bulk_link_issues — inspect or create multiple issue links

• 🧩 jira_get_subtasks / jira_create_subtask — inspect or create sub-tasks

• 🧬 jira_clone_issue — clone an issue with optional field overrides

• 👤 jira_assign_issue — assign issues by name or key

• 👥 jira_find_user — search Jira users for assignment/collaboration flows

• 📋 jira_get_transitions — list currently available transitions for an issue

• 📅 jira_get_my_worklogs — list the authenticated user's Tempo worklogs

• 📅 jira_update_worklog / jira_delete_worklog — correct or remove Tempo worklogs

• 📊 jira_export_project_timesheet — export a project's full Tempo timesheet (all members) to xlsx/xls/csv

• 📎 jira_add_attachment — upload workspace files as issue attachments

• 📤 jira_upload_attachment_content — attach AI-generated content (text, CSV, JSON…) directly without a local file

• 🗂️ jira_get_projects / jira_get_components / jira_get_priorities — discover common Jira metadata

• 🔀 jira_sync_gitlab_review_defects — sync GitLab MR review comments into Jira Review Defects (mrState or single mrIid)

• 🛡️ Clean SESSION_EXPIRED / AUTH_REQUIRED errors with reauthentication hints

• 🖥️ Three CLI utilities for session management

Requirements

• Node.js >= 20

• Access to an internal Jira 8 instance (SSO)

Quick Start (End Users)

No cloning or building required. Install via npm or use npx directly.

Step 1 — Install Playwright Chromium

Required once for the SSO browser login flow:

npx -y playwright install chromium

Step 2 — Authenticate with Jira

Replace the URL with your actual Jira instance. Choose one method:

Option A — Interactive SSO (recommended for MFA / multi-step IdP)

JIRA_BASE_URL=https://jira.yourcompany.com npx -y -p @cuongph.dev/jira-mcp jira-auth-login

A browser window opens. Complete SSO manually. The session is saved to .jira/session.json (or ~/.jira/jira-mcp/session.json for global npx usage).

Option B — Basic Auth with credentials

Set both JIRA_EMAIL and JIRA_PASSWORD in your MCP client env block or in .env (see .env.example). The server tries the stored cookie session first, then HTTP Basic Auth. It does not open a browser from MCP tool calls. If both fail, run Option A (jira-auth-login). MFA or complex SSO requires Option A.

Verify the session is active:

JIRA_BASE_URL=https://jira.yourcompany.com npx -y -p @cuongph.dev/jira-mcp jira-auth-check

Step 3 — Add to your MCP client

No separate server process needed — the MCP client spawns and manages the process automatically via stdio.

Gemini CLI

gemini mcp add jira npx -y @cuongph.dev/jira-mcp --env JIRA_BASE_URL=https://jira.yourcompany.com

Cursor

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

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@cuongph.dev/jira-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://jira.yourcompany.com",
        "GITLAB_TOKEN": "glpat-xxxx",
        "GITLAB_PROJECTS_JSON": "{\"PROJ\":[{\"name\":\"app-frontend\",\"gitlabBaseUrl\":\"https://gitlab.example.com\",\"projectPath\":\"group/app-frontend\"}]}"
      }
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@cuongph.dev/jira-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://jira.yourcompany.com",
        "GITLAB_TOKEN": "glpat-xxxx",
        "GITLAB_PROJECTS_JSON": "{\"PROJ\":[{\"name\":\"app-frontend\",\"gitlabBaseUrl\":\"https://gitlab.example.com\",\"projectPath\":\"group/app-frontend\"}]}"
      }
    }
  }
}

Tip: You can omit the env block and load settings from:

• source checkout: <repo>/.env

• npm/npx install: ~/.jira/jira-mcp/.env

Supported variables include JIRA_BASE_URL (required), optional JIRA_EMAIL / JIRA_PASSWORD for HTTP Basic Auth, LOG_LEVEL, and GitLab sync vars (GITLAB_TOKEN, GITLAB_PROJECTS_JSON, etc.). See .env.example.

For GitLab sync, put GITLAB_TOKEN and GITLAB_PROJECTS_JSON in the MCP env block or .env. MCP clients do not pass custom top-level blocks like "config": { ... } to the server process.

Restart your MCP client after saving the config.

Session Management

Development Setup

For contributors and developers working on the source code.

1. Clone and install

git clone <repo-url>
cd jira-run-mcp
npm install

2. Install Playwright browsers

npx playwright install chromium

3. Configure environment

cp .env.example .env

Edit .env:

JIRA_BASE_URL=https://jira.yourcompany.com

See .env.example for all available options.

4. Authenticate

Interactive SSO:

npm run jira-auth-login

A browser window will open. Complete the SSO login manually. Session is saved to .jira/session.json.

Optional Basic Auth: add both JIRA_EMAIL and JIRA_PASSWORD to .env (see .env.example). On the next MCP tool call the stored cookie is tried first; Basic Auth is used only if the cookie is missing or rejected. MCP never launches Playwright — use jira-auth-login for SSO.

npm run jira-auth-check

5. Build

npm run build

6. Add to MCP client (local build)

Use the local dist/server.js instead of the npm package.

Cursor (.cursor/mcp.json in the repo, or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "jira-run-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/jira-run-mcp/dist/server.js"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Add JIRA_BASE_URL and optional JIRA_EMAIL / JIRA_PASSWORD to the env block if you do not rely on .env alone.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

The .env file in the project root is loaded automatically — you only need env in MCP config for overrides (e.g. LOG_LEVEL) or secrets you prefer not to store in .env.

CLI Utilities (dev)

MCP Tools

jira_get_issue

Fetch a single Jira issue by key.

Input:

Output: Key, summary, description, status, assignee, reporter, priority, issue type, created/updated timestamps, URL.

jira_search_issues

Execute a JQL query and return a compact issue list.

Input:

Output: Total count + list of issues (key, summary, status, assignee, priority, updated, URL).

jira_daily

Return a read-only daily Jira project report with counts, status/progress distribution, due and overdue work, weighted progress, blocker/risk signals, analysis, and navigation hints.

Input: projectKey (required), optional date (yyyy-MM-dd, local today by default), maxIssues (1-200, default 50), and maxBlockers (1-50, default 20).

Docs: docs/tools/jira_daily.md

jira_daily_briefing

Turn the authoritative daily project data into a fixed-format Vietnamese briefing for a project manager. The tool is read-only and limits issue evidence lookups to the highest-impact concerns.

Input: projectKey (required), optional date, maxConcerns (1-20, default 5), and audience (default project manager).

Docs: docs/tools/jira_daily_briefing.md

jira_smart_search

Search by issue key, explicit JQL, or natural-language filters.

Input:

Output: Direct issue lookup or compact search results with generated/executed JQL.

jira_create_issue

Create a Jira issue for a specific issue type.

Input:

Output: Confirmation with created issue key, summary, issue type, and browser URL.

jira_sync_gitlab_review_defects

Sync top-level GitLab MR review comments into Jira Review Defect issues. Requires GITLAB_TOKEN and GitLab project links. Preferred MCP setup is GITLAB_PROJECTS_JSON in the MCP env block (stringified JSON). Fallback map file path is .jira/gitlab-projects.json in a source checkout, or ~/.jira/jira-mcp/gitlab-projects.json when running @cuongph.dev/jira-mcp via npm/npx. Each mapping entry must include a non-empty repository name; generated summaries use [Review Code][<name>][MR !<IID>] ... to identify the repository.

Input:

Docs: docs/tools/jira_sync_gitlab_review_defects.md

jira_add_worklog

Log work on a Jira issue through Tempo Timesheets.

Input:

Output: Confirmation with issue details, worker, date, duration, and Tempo worklog IDs.

jira_add_comment

Add a comment to a Jira issue.

Input:

Output: Confirmation with comment id and browser URL.

jira_transition_issue

Transition a Jira issue to a target workflow state.

Input:

Provide exactly one of transitionId or transitionName.

Output: Confirmation with issue key, transition id, and browser URL.

jira_get_create_meta

Return static create metadata for supported Jira issue types.

Input:

Output: Required fields, optional fields, and known option sets from src/jira/constants.ts.

jira_get_edit_meta

Return live editable fields for a specific issue.

Input:

Output: Field IDs, labels, required flags, schema types, and allowed values returned by Jira.

jira_update_issue_fields

Update a curated set of fields on an existing issue.

Input:

Output: Confirmation with updated field ids and browser URL.

jira_validate_issue_update

Validate an issue update without writing.

Input:

Output: Validation status, normalized update payload, and any fields not editable according to live edit metadata.

jira_bulk_update_issue_fields

Update fields on multiple issues with explicit dry-run control.

Input:

Output: Per-issue status table. Later items continue after per-issue failures.

jira_bulk_transition_issues

Transition multiple issues with explicit dry-run control.

Input:

Output: Per-issue status table with resolved transition ids. Later items continue after per-issue failures.

jira_preview_create_issue

Build and validate a create issue payload without sending it to Jira.

Input:

Output: Normalized Jira create payload JSON.

jira_get_audit_context

Fetch compact context for LLM review of one issue.

Input:

Output: Issue summary, key fields, description, issue links, subtasks, and optional comments.

jira_link_issues

Create a Jira issue link between two issues.

Input:

Output: Confirmation with issue keys, link type, and link id.

jira_get_issue_links

List issue links for a Jira issue.

Input:

Output: Link direction, type, relationship, linked issue key, summary, and status.

jira_get_subtasks

List subtasks for a Jira issue.

Input:

Output: Subtask key, summary, status, assignee, priority, and URL.

jira_create_subtask

Create a subtask under a parent issue.

Input:

Output: Confirmation with parent key, created subtask key, and browser URL.

jira_clone_issue

Clone an issue by copying core fields.

Input:

Output: Confirmation with source key, cloned issue key, and browser URL.

jira_bulk_link_issues

Create multiple issue links sequentially.

Input:

Output: Per-link status table. If one link fails, later links are still attempted and the MCP result is marked as an error.

jira_assign_issue

Assign a Jira issue to a user.

Input:

Output: Confirmation with assignee and browser URL.

jira_find_user

Search Jira users for assignment and collaboration flows.

Input:

Output: Display name, username, user key, active flag, and email if Jira exposes it.

jira_get_transitions

List the currently available workflow transitions for an issue.

Input:

Output: Transition ids, names, and destination statuses.

jira_update_comment

Update an existing issue comment.

Input:

Output: Confirmation with issue key, comment id, and browser URL.

jira_delete_comment

Delete an issue comment by id.

Input:

Output: Confirmation with issue key and deleted comment id.

jira_get_my_worklogs

List the authenticated user's Tempo worklogs.

Input:

Output: Tempo worklog ids, issue keys, dates, durations, and comments.

jira_update_worklog

Update a Tempo worklog by id.

Input:

Output: Confirmation with updated Tempo id, issue key, date, and duration.

jira_delete_worklog

Delete a Tempo worklog by id.

Input:

Output: Confirmation with deleted Tempo id.

jira_export_project_timesheet

Export a project's full Tempo timesheet — worklogs from all members, not a hand-picked worker list — using Tempo's own export flow. The file is written to the ATTACHMENT_WORKSPACE downloads folder.

Input:

Output: Project key, period, resolved format, absolute file path, and file size.

Docs: docs/tools/jira_export_project_timesheet.md

jira_add_attachment

Upload a local file from the allowed workspace directory to an issue.

Input:

Files outside the configured ATTACHMENT_WORKSPACE are rejected. Set the env var to restrict the allowed root directory.

Output: Uploaded attachment ids, filenames, sizes, and issue URL.

jira_upload_attachment_content

Upload in-memory content as a Jira issue attachment — no local file needed.

Input:

Output: Uploaded attachment id, filename, size, MIME type, and issue URL.

jira_get_projects

List Jira projects visible to the authenticated user.

Input: none.

Output: Project keys, names, ids, and browser URLs.

jira_get_components

List components for a Jira project.

Input:

Output: Component ids, names, and descriptions.

jira_get_priorities

List Jira priorities configured in the instance.

Input: none.

Output: Priority ids, names, and descriptions.

Project Structure

src/
├── server.ts              # MCP server entry point
├── config.ts              # Env var validation (Zod)
├── errors.ts              # Typed error classes & factories
├── types.ts               # Shared TypeScript types
├── auth/
│   ├── session-store.ts   # Read/write/clear session.json
│   ├── session-manager.ts # Session validation against Jira
│   └── playwright-auth.ts # Headed SSO browser flow
├── jira/
│   ├── endpoints.ts       # URL builders (REST API v2)
│   ├── mappers.ts         # Raw payload → typed output shapes
│   ├── adf.ts             # ADF type interfaces + low-level builders
│   ├── body-normalizer.ts # normalizeJiraBody (markdown/plain/adf → ADF)
│   ├── markdown-to-adf.ts # Markdown AST → ADF converter (remark)
│   ├── create-meta.ts     # Static issue create metadata helpers
│   ├── create-issue.ts    # Create-issue validation and payload helpers
│   ├── edit-meta.ts       # Live issue edit metadata normalization
│   ├── user-search.ts     # User search normalization
│   ├── transition-resolution.ts # Transition name resolution
│   ├── update-issue.ts    # Curated field update normalization
│   └── http-client.ts     # Cookie-authenticated Jira HTTP client
├── tools/
│   ├── add-attachment.ts  # jira_add_attachment handler
│   ├── add-comment.ts     # jira_add_comment handler
│   ├── bulk-link-issues.ts # jira_bulk_link_issues handler
│   ├── clone-issue.ts     # jira_clone_issue handler
│   ├── create-subtask.ts  # jira_create_subtask handler
│   ├── get-issue.ts       # jira_get_issue handler
│   ├── get-issue-links.ts # jira_get_issue_links handler
│   ├── get-subtasks.ts    # jira_get_subtasks handler
│   ├── find-user.ts       # jira_find_user handler
│   ├── get-components.ts  # jira_get_components handler
│   ├── get-create-meta.ts # jira_get_create_meta handler
│   ├── get-edit-meta.ts   # jira_get_edit_meta handler
│   ├── get-my-worklogs.ts # jira_get_my_worklogs handler
│   ├── get-priorities.ts  # jira_get_priorities handler
│   ├── get-projects.ts    # jira_get_projects handler
│   ├── get-transitions.ts # jira_get_transitions handler
│   ├── link-issues.ts     # jira_link_issues handler
│   ├── assign-issue.ts    # jira_assign_issue handler
│   ├── delete-comment.ts  # jira_delete_comment handler
│   ├── delete-worklog.ts  # jira_delete_worklog handler
│   ├── export-project-timesheet.ts # jira_export_project_timesheet handler
│   ├── search-issues.ts   # jira_search_issues handler
│   ├── smart-search.ts    # jira_smart_search handler
│   ├── add-worklog.ts     # jira_add_worklog handler
│   ├── transition-issue.ts # jira_transition_issue handler
│   ├── update-comment.ts  # jira_update_comment handler
│   ├── update-issue-fields.ts # jira_update_issue_fields handler
│   ├── update-worklog.ts  # jira_update_worklog handler
│   └── create-issue.ts    # jira_create_issue handler
├── cli/
│   ├── auth-login.ts      # jira-auth-login entry point
│   ├── auth-check.ts      # jira-auth-check entry point
│   └── auth-clear.ts      # jira-auth-clear entry point
└── tests/                 # Unit tests (Vitest)

Authentication Flow

Operator
  │
  ▼
npm run jira-auth-login
  │
  ├── Playwright opens browser (headed)
  ├── Operator completes SSO manually
  ├── storageState saved → .jira/session.json
  └── Session validated immediately
  
MCP Tool Call
  │
  ├── Load .jira/session.json
  ├── Validate against /rest/api/2/myself
  ├── Extract cookies → build HTTP request
  └── Return normalized Jira data
  
Session Expired?
  │
  └── Returns [SESSION_EXPIRED] error
      → "Run: npm run jira-auth-login"

Development Commands

# Type check
npx tsc --noEmit

# Run tests
npm test

# Watch mode
npm run test:watch

# Build for production
npm run build

# Run directly (dev mode, reads .env)
npm run dev

Testing with MCP Inspector

MCP Inspector is the official GUI tool for interactively testing MCP servers — call tools, inspect inputs/outputs, and debug without an AI client.

Option A — dev mode (no build required):

npx @modelcontextprotocol/inspector tsx src/server.ts

tsx compiles TypeScript on-the-fly. Changes are picked up on every Inspector session restart without a rebuild step.

Option B — built bundle:

npm run build
npx @modelcontextprotocol/inspector node dist/server.js

Both options read the .env file in the project root automatically.

After the Inspector starts, open the URL it prints (usually http://localhost:5173) in your browser, select a tool from the sidebar, fill in the inputs, and click Run.

Error Codes

Security Notes

• .env and .jira/session.json are git-ignored and must never be committed.

• Session cookies give full Jira access as the authenticated user — treat them like passwords.

• The session file is stored locally only; no remote storage is involved.