Jira MCP Server

MCP (Model Context Protocol) server for Jira Cloud. Provides AI assistants with tools to read, search, create, update, transition, link, comment, and attach files to Jira issues via the REST API v3. Text fields (descriptions, comments) support Markdown formatting.

Prerequisites

• Node.js 18+
• Jira Cloud instance
• API Token for your Atlassian account (create one here)

Setup

npm install
npm run build

Create a .env file (see .env.example):

JIRA_BASE_URL=https://jira.example.com
[email protected]
JIRA_API_TOKEN=your-api-token

Running as MCP Server

Add to your Cursor mcp.json:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["C:\\repos\\Custom-MCP\\Jira\\dist\\index.js"]
    }
  }
}

Or run directly for development (without building):

npm run dev

Tools

get_my_tasks

Returns active tasks assigned to the current user.

JQL: assignee = currentUser() AND status NOT IN (Done, Cancelled) ORDER BY priority DESC

get_task_details

Returns full context for a single issue: summary, description, status, assignee, comments, attachments, and issue links.

Response includes issueLinks[] with id, linkType, direction, relation, and linked issue details. Use the link id with unlink_issues to remove a link.

search_tasks

Searches issues by text query or raw JQL. Provide either query or jql, not both.

update_task_status

Transitions an issue to a new status. Fetches available transitions first, matches by name (case-insensitive), then executes.

create_task

Creates a new Jira issue. Description supports Markdown formatting.

update_task

Updates fields on an existing Jira issue. Only provided fields are changed. Description supports Markdown formatting.

link_issues

Creates a link between two Jira issues. Use get_task_details to see existing links.

Common link types: Blocks (blocks / is blocked by), Relates (relates to), Duplicate (duplicates / is duplicated by), Cloners (clones / is cloned by).

unlink_issues

Removes a link between two issues by link ID. Get the link ID from get_task_details → issueLinks[].id.

add_comment

Adds a comment to an issue. Supports Markdown formatting.

attach_file

Uploads a file from disk and attaches it to an issue. Optionally adds a comment in the same call.

CLI

A standalone CLI runner is included for manual testing outside of MCP. It uses the same .env config and the same Jira client.

npm run cli -- <tool_name> [json_args]

Examples (key=value — works everywhere)

The recommended way to pass arguments. No quoting issues on any OS or shell.

npm run cli -- --help
npm run cli -- get_my_tasks
npm run cli -- get_my_tasks max_results=5
npm run cli -- get_task_details issue_key=PROJ-123
npm run cli -- search_tasks query="oauth bug" max_results=5
npm run cli -- search_tasks jql="project = PROJ AND status = Open"
npm run cli -- create_task project=PROJ summary="Fix login bug" issue_type=Bug description="**Steps:** ..." parent=PROJ-100
npm run cli -- update_task issue_key=PROJ-123 summary="Updated title" description="New **description**"
npm run cli -- update_task_status issue_key=PROJ-123 transition_name="In Progress"
npm run cli -- add_comment issue_key=PROJ-123 comment="Fixed in PR #42"
npm run cli -- attach_file issue_key=PROJ-123 file_path=C:\path\to\report.pdf
npm run cli -- attach_file issue_key=PROJ-123 file_path=C:\path\to\report.pdf comment="See attached report"
npm run cli -- link_issues link_type=Blocks outward_issue=PROJ-1 inward_issue=PROJ-2
npm run cli -- unlink_issues link_id=12345

Examples (JSON — Bash / macOS / Linux)

JSON is also accepted as a single argument when wrapped in single quotes:

npm run cli -- get_task_details '{"issue_key": "PROJ-123"}'
npm run cli -- search_tasks '{"query": "oauth bug", "max_results": 5}'

Windows note: npm.cmd passes arguments through cmd.exe, which strips double quotes. Use the key=value format on Windows instead of JSON.

Output is formatted JSON printed to stdout. Errors print to stderr with a non-zero exit code.

Project Structure

src/
  index.ts           — MCP server entry point (stdio transport)
  cli.ts             — CLI entry point for manual testing
  config.ts          — .env loader, validates JIRA_BASE_URL / EMAIL / API_TOKEN
  adf.ts             — ADF ↔ Markdown/plain-text conversion
  jira-client.ts     — HTTP wrapper over native fetch with Basic Auth
  response.ts        — successResponse / errorResponse helpers
  tools/
    getMyTasks.ts
    getTaskDetails.ts
    searchTasks.ts
    updateTaskStatus.ts
    addComment.ts
    attachFile.ts
    createTask.ts
    updateTask.ts
    linkIssues.ts
    unlinkIssues.ts
docs/
  markdown-formatting.md  — Supported Markdown syntax reference