Skip to main content
Glama
mcp-server-jira

mcp-server-jira

by sina-haseli

@deomi/mcp-server-jira

npm version CI License: MIT

A Model Context Protocol (MCP) server that lets an AI agent manage a self-hosted Jira instance over the Jira REST API v2 — create and edit Stories, search, transition workflows, manage boards & sprints, read burndown data, and (with confirmation) perform admin actions. Built for a PRD automation workflow, usable as a general Jira agent backend.

  • Transport: stdio

  • Auth: HTTP Basic (email:api_token)

  • 16 tools across Story CRUD, workflow, multi-project, and Agile

  • Safety first: read/write/destructive annotations + server-enforced confirmation on risky actions


Table of contents


Related MCP server: Jira MCP Integration

Install

Once published, run it directly with npx (no global install needed):

npx -y @deomi/mcp-server-jira

Or install globally:

npm install -g @deomi/mcp-server-jira
mcp-server-jira

Or from source:

git clone https://github.com/sina-haseli/mcp-server-jira.git
cd mcp-server-jira
npm install
npm run build
node dist/index.js

The server reads config from the environment, so it won't do anything useful until you supply credentials (see below). It logs to stderr and speaks MCP JSON-RPC on stdout.


Configuration

Provide settings in either of two ways. Per-setting precedence is: environment variable → config file.

Point JIRA_MCP_CONFIG at a JSON file:

{
  "baseUrl": "https://jira.yourcompany.com",
  "userEmail": "you@yourcompany.com",
  "apiToken": "your_api_token_here",
  "projectKey": "PRD",
  "storyIssueType": "Story",
  "outlineLinkField": "customfield_10100",
  "storyPointsField": "customfield_10016"
}

A template is provided in jira-mcp.config.example.json. Keep your real file out of version control (the default .gitignore already ignores jira-mcp.config.json).

Option B — environment variables

Variable

Required

Description

JIRA_BASE_URL

✅

Base URL, e.g. https://jira.yourcompany.com

JIRA_USER_EMAIL

✅

Account email/username for Basic Auth

JIRA_API_TOKEN

✅

API token / Personal Access Token (or password) for Basic Auth

JIRA_PROJECT_KEY

➖

Default project key (optional — override per call)

JIRA_STORY_ISSUE_TYPE

➖

Story issue type name (default Story)

JIRA_OUTLINE_LINK_FIELD

➖

Custom field id for the Outline link (e.g. customfield_10100)

JIRA_STORY_POINTS_FIELD

➖

Custom field id for story points (default customfield_10016)

JIRA_MCP_CONFIG

➖

Path to a JSON config file (Option A)

Required settings are validated at startup; if any are missing the server logs a clear error to stderr and exits. JIRA_PROJECT_KEY is optional — see Multiple projects.

All API calls target ${JIRA_BASE_URL}/rest/api/2 (core), /rest/agile/1.0 (boards & sprints), and /rest/greenhopper/1.0 (burndown).


Use with Claude Desktop

Open Settings → Developer → Edit Config (creates %APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and add:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["D:\\projects\\mcp-server-jira\\dist\\index.js"],
      "env": {
        "JIRA_MCP_CONFIG": "D:\\projects\\mcp-server-jira\\jira-mcp.config.json"
      }
    }
  }
}

Or, once published to npm, with no local checkout:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@deomi/mcp-server-jira"],
      "env": {
        "JIRA_MCP_CONFIG": "D:\\projects\\mcp-server-jira\\jira-mcp.config.json"
      }
    }
  }
}

Fully quit Claude Desktop (tray → Quit, not just close the window) and reopen. Then run get_project_info from the chat to confirm auth and connectivity.


Tools

Story CRUD

Tool

Purpose

create_story

Create a Story from a PRD (acceptance criteria + Outline link)

get_story

Fetch a Story's key fields by issue key

update_story

Update selected fields of a Story

search_stories

JQL text search for Stories (duplicate detection)

get_project_info

Project metadata: priorities, issue types, story type id

add_comment

Add a plain-text comment to a Story

Workflow & guarded actions

Tool

Purpose

transition_story

List or perform workflow transitions. Transitions to Done/Closed need confirm.

delete_story

Permanently delete a Story. Requires confirm: true.

Projects (multi-project)

Tool

Purpose

list_projects

List all visible projects (discover project_key values)

create_project

Admin. Create a project. Requires confirm: true.

create_issue_type

Admin. Create a global issue type. Requires confirm: true.

Agile / burndown (requires Jira Software)

Tool

Purpose

list_boards

List Agile boards (scrum/kanban) — get a board id

list_sprints

List a board's sprints with start/end dates and state

get_sprint_burndown

Burndown data for AI analysis (committed vs done vs remaining)

create_board

Create a scrum/kanban board from a saved filter. Requires confirm.

create_sprint

Create a sprint on a board. Requires confirm: true.

Every tool returns structured JSON. Errors are returned as structured objects ({ error: true, message, ... }) — the server never throws unhandled exceptions out of a tool.


Safety: human approval for risky actions

Two complementary mechanisms protect destructive and high-impact operations:

  1. MCP annotations — every tool declares readOnlyHint / destructiveHint / idempotentHint / openWorldHint. The host (e.g. Claude) uses these to decide when to prompt the human. Read-only tools (get_*, search_*, list_*) are flagged as such; update_story and delete_story are flagged destructive.

  2. Server-enforced confirmation — delete_story, terminal transition_story calls, and all admin create_* tools (create_project, create_issue_type, create_board, create_sprint) require an explicit confirm: true. Without it the tool makes no API call and returns a requires_confirmation warning describing the impact, so the agent (and human) must opt in deliberately.


Multiple projects

JIRA_PROJECT_KEY / projectKey is an optional default. Every project-scoped tool (create_story, search_stories, get_project_info, list_boards) accepts an optional project_key argument that overrides the default for that call. Use list_projects to discover available keys. If no project_key is passed and no default is configured, the tool returns a clear error rather than guessing.


Burndown

An MCP server can't return a rendered chart image, but get_sprint_burndown returns the underlying data: a reliable computed summary (committed / completed / remaining story points and issue counts by status, derived from the sprint's issues) plus a best-effort raw GreenHopper burndown time-series (burndown_chart_raw) when that internal endpoint is available. The AI can summarize progress, flag scope changes, and describe the burndown from this data. Story points are read from JIRA_STORY_POINTS_FIELD.


Development

npm install
npm run dev      # ts-node src/index.ts
npm run build    # tsc -> dist/
npm start        # node dist/index.js

Project layout:

src/
├── index.ts            # bootstrap (stdio transport)
├── config.ts           # env / config-file loading + validation
├── logger.ts           # stderr logger
├── jira/
│   ├── client.ts       # axios clients (core / agile / greenhopper) + browseUrl
│   └── errors.ts       # error mapping + ok()/fail() result helpers
└── tools/
    ├── index.ts        # registerAllTools()
    ├── shared.ts       # registerTool wrapper, annotations, confirm + project helpers
    └── *.ts            # one file per tool

Releasing

Releases are automated by .github/workflows/release.yml: pushing a v* tag builds the package, publishes it to npm (with provenance), and creates a GitHub Release with auto-generated notes.

One-time setup: add a repo secret NPM_TOKEN (an npm Automation access token) under Settings → Secrets and variables → Actions.

Cut a release:

npm version patch   # or minor / major — bumps package.json and creates the tag
git push --follow-tags

The workflow verifies the tag matches package.json before publishing.


License

MIT © Sina Haseli

Available Tools

16 tools
add_commentA

Adds a plain-text comment to a Story. Used, for example, to log when the PRD doc is updated in Outline. Returns { success, comment_id }.

Inputs: body (required), issue_key (required).

create_boardA

Creates a Jira Software Agile board (scrum/kanban) from an existing saved filter. Guarded: requires confirm:true. Requires Jira Software and permission to manage boards.

Inputs: name (required), type (required), filter_id (required), confirm.

create_issue_typeA

Creates a new issue type in Jira (admin only). Guarded: requires confirm:true. Issue types are global across the instance.

Inputs: name (required), type, confirm, description.

create_projectA

Creates a new Jira project (admin only). Guarded: requires confirm:true. Some Jira versions require a template_key; if creation fails for that reason, retry with template_key.

Inputs: key (required), lead (required), name (required), confirm, +4 more.

create_sprintA

Creates a sprint on a scrum board. Guarded: requires confirm:true. Requires Jira Software.

Inputs: name (required), board_id (required), goal, confirm, +2 more.

create_storyA

Creates a new Jira Story from a PRD. Formats the description with acceptance criteria and an optional Outline PRD link, sets labels and priority, and (if an Outline URL is supplied) attaches it as a remote link. Returns the created issue key, id, and browse URL.

Inputs: labels (required), summary (required), priority (required), description (required), +4 more.

delete_storyA
DestructiveIdempotent

PERMANENTLY deletes a Story by issue key. This is irreversible. Guarded: without confirm:true it returns a warning instead of deleting. Intended for human-approved cleanup only.

Inputs: issue_key (required), confirm, delete_subtasks.

get_project_infoA
Read-only

Returns metadata for a Jira project: project key/name, available priorities, and the issue type id for Stories. Defaults to the configured project; pass project_key to target another. Use this to validate input before creating issues.

Inputs: project_key.

get_sprint_burndownA
Read-only

Returns burndown data for a sprint so the AI can analyze/summarize progress (this is data, not a rendered chart image). Includes a reliable computed summary (committed vs completed vs remaining story points, issue counts by status) plus best-effort raw GreenHopper burndown time-series. Requires Jira Software.

Inputs: board_id (required), sprint_id (required).

get_storyA
Read-only

Retrieves a Story by its issue key (e.g. PRD-42). Returns the key fields an AI agent needs: summary, description, status, labels, priority, and browse URL.

Inputs: issue_key (required).

list_boardsA
Read-only

Lists Jira Software Agile boards (scrum/kanban). Returns board id, name and type. The board id is needed to list sprints and fetch burndown data. Requires Jira Software (Agile) on the instance.

Inputs: project_key, all_projects.

list_projectsA
Read-only

Lists all Jira projects visible to the account. Returns key, name, id and project type for each. Use this to discover which project_key to pass to other tools when working across multiple projects.

Inputs: no named parameters.

list_sprintsA
Read-only

Lists sprints for a given Agile board. Returns sprint id, name, state, and start/end dates. Use the sprint id with get_sprint_burndown. Requires a scrum board.

Inputs: board_id (required), state.

search_storiesA
Read-only

Searches for Stories in the configured project using a plain-text query (wrapped in JQL). Useful for checking duplicates before creating a new Story. Returns an array of { key, summary, status, labels, url }.

Inputs: query (required), max_results, project_key.

transition_storyA

Moves a Story through its workflow (e.g. To Do -> In Progress -> Done). Call without transition to list available transitions. Transitions into a terminal status (Done/Closed/Resolved) are guarded and require confirm:true.

Inputs: issue_key (required), comment, confirm, transition.

update_storyA
DestructiveIdempotent

Updates fields of an existing Story (e.g. after human approval edits). Only the fields you supply are changed. Returns { success, key }.

Inputs: issue_key (required), labels, summary, priority, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 16 tools

    Disambiguation5/5

    Every tool targets a distinct resource and action: story CRUD, comments, transitions, project metadata, and Agile board/sprint operations are clearly separable. Even with shared verbs like 'get' or 'create', the noun targets prevent confusion.

    Naming Consistency5/5

    Tool names consistently follow verb_noun conventions with get/create/update/delete/list/transition/add prefixes. Minor pluralization in search_stories and the info suffix in get_project_info do not break the overall pattern.

    Tool Count4/5

    16 tools is slightly above the ideal 3-15 range but appropriate for a Jira server covering both story lifecycle management and Agile board/sprint operations. Each tool appears purposeful with minimal redundancy.

    Completeness4/5

    The story lifecycle is well covered: get, create, update, delete, search, transition, and comment. Some minor gaps exist around generic issue operations and board/sprint deletion, but the set covers the core PRD-to-Jira and Agile tracking workflows well.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to interact with Jira Cloud instances for comprehensive issue management including creating, updating, searching issues, managing comments, workflow transitions, and project metadata discovery. Supports JQL queries, user search, and custom field operations with secure API token authentication.
      12
      611 npm
      8
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with Jira Cloud through the REST API, supporting project management, issue operations (create, read, update, delete), JQL search, task assignments, and status transitions.
      -
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI agents to manage Jira projects and issues using natural language, including creating, updating, searching issues, managing sprints, and more via the Jira API.
      36
      1,667 npm
      1
      MIT