mcp-server-jira
This MCP server enables an AI agent to comprehensively manage a self-hosted Jira instance via the Jira REST API v2 and Agile/GreenHopper APIs, providing 16 tools across the following areas:
Story Management
Create, retrieve, update, search (JQL-backed), and delete stories
Specify summary, description, acceptance criteria, labels, priority, story points, and optional Outline PRD links
Add comments to stories
Workflow & Guarded Actions
Transition stories through workflow states (e.g., To Do → In Progress → Done)
Terminal transitions (e.g., Done/Closed) and destructive actions (e.g., delete) require explicit
confirm: true
Multi-Project & Admin Management
List all visible projects and retrieve project metadata (priorities, issue types)
Create new projects and global issue types (admin only, requires
confirm: true)
Agile Management (Jira Software required)
List Agile boards (scrum/kanban) and sprints with state and date info
Retrieve sprint burndown data (committed vs. completed vs. remaining points, issue counts, GreenHopper time-series) for AI analysis
Create boards and sprints (requires
confirm: true)
Safety Features
Read-only tools (
get_*,search_*,list_*) are annotated as safeHigh-impact or destructive operations require
confirm: trueor return a warning without actingAll tools return structured JSON, including structured error objects
Configuration & Transport
Configured via environment variables or a JSON config file (Jira URL, credentials, default project key, custom field IDs)
Uses HTTP Basic Auth (email + API token)
Communicates via stdio using MCP JSON-RPC
Manages Jira Stories via the Jira REST API v2, providing CRUD operations, workflow transitions, search, and project info for Jira issues.
Provides agile burndown data, sprint and board listing for Jira Software projects, enabling AI-driven analysis of sprint progress.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-server-jira show me open stories in project PRD"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@deomi/mcp-server-jira
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-jiraOr install globally:
npm install -g @deomi/mcp-server-jira
mcp-server-jiraOr 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.jsThe 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.
Option A — a single config file (recommended for desktop clients)
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 |
| ✅ | Base URL, e.g. |
| ✅ | Account email/username for Basic Auth |
| ✅ | API token / Personal Access Token (or password) for Basic Auth |
| ➖ | Default project key (optional — override per call) |
| ➖ | Story issue type name (default |
| ➖ | Custom field id for the Outline link (e.g. |
| ➖ | Custom field id for story points (default |
| ➖ | 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 a Story from a PRD (acceptance criteria + Outline link) |
| Fetch a Story's key fields by issue key |
| Update selected fields of a Story |
| JQL text search for Stories (duplicate detection) |
| Project metadata: priorities, issue types, story type id |
| Add a plain-text comment to a Story |
Workflow & guarded actions
Tool | Purpose |
| List or perform workflow transitions. Transitions to Done/Closed need |
| Permanently delete a Story. Requires |
Projects (multi-project)
Tool | Purpose |
| List all visible projects (discover |
| Admin. Create a project. Requires |
| Admin. Create a global issue type. Requires |
Agile / burndown (requires Jira Software)
Tool | Purpose |
| List Agile boards (scrum/kanban) — get a board id |
| List a board's sprints with start/end dates and state |
| Burndown data for AI analysis (committed vs done vs remaining) |
| Create a scrum/kanban board from a saved filter. Requires |
| Create a sprint on a board. Requires |
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:
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_storyanddelete_storyare flagged destructive.Server-enforced confirmation —
delete_story, terminaltransition_storycalls, and all admincreate_*tools (create_project,create_issue_type,create_board,create_sprint) require an explicitconfirm: true. Without it the tool makes no API call and returns arequires_confirmationwarning 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.jsProject 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 toolReleasing
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-tagsThe workflow verifies the tag matches package.json before publishing.
License
MIT © Sina Haseli
Available Tools
16 toolsadd_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_storyADestructiveIdempotent
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_infoARead-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_burndownARead-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_storyARead-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_boardsARead-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_projectsARead-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_sprintsARead-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_storiesARead-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_storyADestructiveIdempotent
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
Scored across 16 tools
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.
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.
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.
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
Related MCP Connectors
Task manager your agent can fully operate: boards, tasks, sprints, roles, worklogs, day planner.
Connect to Atlassian Jira, Confluence, Loom, and more to search, create, and manage your work.
Task and bug tracker for AI coding agents: 75 tools to file, triage and update work.
1Manage Jensi projects, tasks, sprints and the AI suggestion inbox from your AI assistant.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables 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.12611 npm8MIT
- FlicenseNot gradedqualityDmaintenanceEnables 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.-
- AlicenseBqualityDmaintenanceEnables AI agents to manage Jira projects and issues using natural language, including creating, updating, searching issues, managing sprints, and more via the Jira API.361,667 npm1MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with self-hosted Jira instances for issue management, search, comments, and workflow transitions.19MIT