{"_id":"@deomi/mcp-server-jira","name":"@deomi/mcp-server-jira","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@deomi/mcp-server-jira","version":"1.0.0","description":"MCP server for managing Jira Stories, sprints and boards in a self-hosted Jira instance (PRD automation workflow)","license":"MIT","author":{"name":"Sina Haseli","email":"sina.haseli@gmail.com"},"homepage":"https://github.com/sina-haseli/mcp-server-jira#readme","repository":{"type":"git","url":"git+https://github.com/sina-haseli/mcp-server-jira.git"},"bugs":{"url":"https://github.com/sina-haseli/mcp-server-jira/issues"},"keywords":["mcp","model-context-protocol","jira","jira-rest-api","claude","ai","agent","stories","sprints","burndown"],"type":"commonjs","main":"dist/index.js","bin":{"mcp-server-jira":"dist/index.js"},"engines":{"node":">=18"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"ts-node src/index.ts","prepublishOnly":"npm run build"},"publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","axios":"^1.6.0","dotenv":"^16.0.0","zod":"^3.25.0"},"devDependencies":{"@types/node":"^20.0.0","ts-node":"^10.9.0","typescript":"^5.0.0"},"_id":"@deomi/mcp-server-jira@1.0.0","gitHead":"2ce7d9bf11ab77a7a58473249f20113eba3f1549","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-hfb3Knh+OcqNNEyf0qIZShEP6WNjCli8fNtsyJH8kmuFq86mo9Kv19/wUU+3cBWhBZyge1kezsqSEXEacrTW2Q==","shasum":"2203ba873334a5d68b2200dde1d6160c4f2af99d","tarball":"https://registry.npmjs.org/@deomi/mcp-server-jira/-/mcp-server-jira-1.0.0.tgz","fileCount":28,"unpackedSize":64049,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@deomi%2fmcp-server-jira@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDAk8LCF0rxt6r4xKiQ1SYRpz9wcWtxjkOrMDOytTMLeQIhAOq5VAfP/bLFB/t9vMAWhheWdNePq51U8E/q2cOD140w"}]},"_npmUser":{"name":"deomi","email":"sina.haseli@gmail.com"},"directories":{},"maintainers":[{"name":"deomi","email":"sina.haseli@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server-jira_1.0.0_1782481390539_0.922365994206094"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-26T13:43:10.388Z","1.0.0":"2026-06-26T13:43:10.678Z","modified":"2026-06-26T13:43:11.014Z"},"maintainers":[{"name":"deomi","email":"sina.haseli@gmail.com"}],"description":"MCP server for managing Jira Stories, sprints and boards in a self-hosted Jira instance (PRD automation workflow)","homepage":"https://github.com/sina-haseli/mcp-server-jira#readme","keywords":["mcp","model-context-protocol","jira","jira-rest-api","claude","ai","agent","stories","sprints","burndown"],"repository":{"type":"git","url":"git+https://github.com/sina-haseli/mcp-server-jira.git"},"author":{"name":"Sina Haseli","email":"sina.haseli@gmail.com"},"bugs":{"url":"https://github.com/sina-haseli/mcp-server-jira/issues"},"license":"MIT","readme":"# @deomi/mcp-server-jira\n\n[![npm version](https://img.shields.io/npm/v/@deomi/mcp-server-jira.svg)](https://www.npmjs.com/package/@deomi/mcp-server-jira)\n[![CI](https://github.com/sina-haseli/mcp-server-jira/actions/workflows/ci.yml/badge.svg)](https://github.com/sina-haseli/mcp-server-jira/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\nA [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets an AI agent\nmanage a **self-hosted Jira** instance over the Jira REST API **v2** — create and edit Stories,\nsearch, transition workflows, manage boards & sprints, read burndown data, and (with confirmation)\nperform admin actions. Built for a PRD automation workflow, usable as a general Jira agent backend.\n\n- **Transport:** stdio\n- **Auth:** HTTP Basic (`email:api_token`)\n- **16 tools** across Story CRUD, workflow, multi-project, and Agile\n- **Safety first:** read/write/destructive annotations + server-enforced confirmation on risky actions\n\n---\n\n## Table of contents\n\n- [Install](#install)\n- [Configuration](#configuration)\n- [Use with Claude Desktop](#use-with-claude-desktop)\n- [Tools](#tools)\n- [Safety: human approval for risky actions](#safety-human-approval-for-risky-actions)\n- [Multiple projects](#multiple-projects)\n- [Burndown](#burndown)\n- [Development](#development)\n- [Releasing](#releasing)\n- [License](#license)\n\n---\n\n## Install\n\nOnce published, run it directly with `npx` (no global install needed):\n\n```bash\nnpx -y @deomi/mcp-server-jira\n```\n\nOr install globally:\n\n```bash\nnpm install -g @deomi/mcp-server-jira\nmcp-server-jira\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/sina-haseli/mcp-server-jira.git\ncd mcp-server-jira\nnpm install\nnpm run build\nnode dist/index.js\n```\n\nThe server reads config from the environment, so it won't do anything useful until you supply\ncredentials (see below). It logs to **stderr** and speaks MCP JSON-RPC on **stdout**.\n\n---\n\n## Configuration\n\nProvide settings in **either** of two ways. Per-setting precedence is: **environment variable → config file**.\n\n### Option A — a single config file (recommended for desktop clients)\n\nPoint `JIRA_MCP_CONFIG` at a JSON file:\n\n```json\n{\n  \"baseUrl\": \"https://jira.yourcompany.com\",\n  \"userEmail\": \"you@yourcompany.com\",\n  \"apiToken\": \"your_api_token_here\",\n  \"projectKey\": \"PRD\",\n  \"storyIssueType\": \"Story\",\n  \"outlineLinkField\": \"customfield_10100\",\n  \"storyPointsField\": \"customfield_10016\"\n}\n```\n\nA template is provided in [`jira-mcp.config.example.json`](jira-mcp.config.example.json). Keep your\nreal file out of version control (the default `.gitignore` already ignores `jira-mcp.config.json`).\n\n### Option B — environment variables\n\n| Variable                  | Required | Description                                                       |\n| ------------------------- | -------- | ----------------------------------------------------------------- |\n| `JIRA_BASE_URL`           | ✅       | Base URL, e.g. `https://jira.yourcompany.com`                     |\n| `JIRA_USER_EMAIL`         | ✅       | Account email/username for Basic Auth                             |\n| `JIRA_API_TOKEN`          | ✅       | API token / Personal Access Token (or password) for Basic Auth   |\n| `JIRA_PROJECT_KEY`        | ➖       | **Default** project key (optional — override per call)            |\n| `JIRA_STORY_ISSUE_TYPE`   | ➖       | Story issue type name (default `Story`)                           |\n| `JIRA_OUTLINE_LINK_FIELD` | ➖       | Custom field id for the Outline link (e.g. `customfield_10100`)   |\n| `JIRA_STORY_POINTS_FIELD` | ➖       | Custom field id for story points (default `customfield_10016`)    |\n| `JIRA_MCP_CONFIG`         | ➖       | Path to a JSON config file (Option A)                             |\n\nRequired settings are validated at startup; if any are missing the server logs a clear error to\nstderr and exits. `JIRA_PROJECT_KEY` is **optional** — see [Multiple projects](#multiple-projects).\n\nAll API calls target `${JIRA_BASE_URL}/rest/api/2` (core), `/rest/agile/1.0` (boards & sprints),\nand `/rest/greenhopper/1.0` (burndown).\n\n---\n\n## Use with Claude Desktop\n\nOpen **Settings → Developer → Edit Config** (creates `%APPDATA%\\Claude\\claude_desktop_config.json`\non Windows, `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS) and add:\n\n```json\n{\n  \"mcpServers\": {\n    \"jira\": {\n      \"command\": \"node\",\n      \"args\": [\"D:\\\\projects\\\\mcp-server-jira\\\\dist\\\\index.js\"],\n      \"env\": {\n        \"JIRA_MCP_CONFIG\": \"D:\\\\projects\\\\mcp-server-jira\\\\jira-mcp.config.json\"\n      }\n    }\n  }\n}\n```\n\nOr, once published to npm, with no local checkout:\n\n```json\n{\n  \"mcpServers\": {\n    \"jira\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@deomi/mcp-server-jira\"],\n      \"env\": {\n        \"JIRA_MCP_CONFIG\": \"D:\\\\projects\\\\mcp-server-jira\\\\jira-mcp.config.json\"\n      }\n    }\n  }\n}\n```\n\n**Fully quit** Claude Desktop (tray → Quit, not just close the window) and reopen. Then run\n`get_project_info` from the chat to confirm auth and connectivity.\n\n---\n\n## Tools\n\n### Story CRUD\n\n| Tool               | Purpose                                                              |\n| ------------------ | ------------------------------------------------------------------- |\n| `create_story`     | Create a Story from a PRD (acceptance criteria + Outline link)      |\n| `get_story`        | Fetch a Story's key fields by issue key                             |\n| `update_story`     | Update selected fields of a Story                                   |\n| `search_stories`   | JQL text search for Stories (duplicate detection)                   |\n| `get_project_info` | Project metadata: priorities, issue types, story type id            |\n| `add_comment`      | Add a plain-text comment to a Story                                 |\n\n### Workflow & guarded actions\n\n| Tool               | Purpose                                                                           |\n| ------------------ | -------------------------------------------------------------------------------- |\n| `transition_story` | List or perform workflow transitions. Transitions to Done/Closed need `confirm`. |\n| `delete_story`     | **Permanently** delete a Story. Requires `confirm: true`.                         |\n\n### Projects (multi-project)\n\n| Tool                | Purpose                                                          |\n| ------------------- | --------------------------------------------------------------- |\n| `list_projects`     | List all visible projects (discover `project_key` values)       |\n| `create_project`    | **Admin.** Create a project. Requires `confirm: true`.          |\n| `create_issue_type` | **Admin.** Create a global issue type. Requires `confirm: true`.|\n\n### Agile / burndown (requires Jira Software)\n\n| Tool                  | Purpose                                                              |\n| --------------------- | ------------------------------------------------------------------- |\n| `list_boards`         | List Agile boards (scrum/kanban) — get a board id                   |\n| `list_sprints`        | List a board's sprints with start/end dates and state               |\n| `get_sprint_burndown` | Burndown **data** for AI analysis (committed vs done vs remaining)   |\n| `create_board`        | Create a scrum/kanban board from a saved filter. Requires `confirm`.|\n| `create_sprint`       | Create a sprint on a board. Requires `confirm: true`.               |\n\nEvery tool returns structured JSON. Errors are returned as structured objects\n(`{ error: true, message, ... }`) — the server never throws unhandled exceptions out of a tool.\n\n---\n\n## Safety: human approval for risky actions\n\nTwo complementary mechanisms protect destructive and high-impact operations:\n\n1. **MCP annotations** — every tool declares `readOnlyHint` / `destructiveHint` / `idempotentHint` /\n   `openWorldHint`. The host (e.g. Claude) uses these to decide when to prompt the human. Read-only\n   tools (`get_*`, `search_*`, `list_*`) are flagged as such; `update_story` and `delete_story` are\n   flagged destructive.\n\n2. **Server-enforced confirmation** — `delete_story`, terminal `transition_story` calls, and all\n   admin `create_*` tools (`create_project`, `create_issue_type`, `create_board`, `create_sprint`)\n   require an explicit `confirm: true`. Without it the tool makes **no** API call and returns a\n   `requires_confirmation` warning describing the impact, so the agent (and human) must opt in\n   deliberately.\n\n---\n\n## Multiple projects\n\n`JIRA_PROJECT_KEY` / `projectKey` is an **optional default**. Every project-scoped tool\n(`create_story`, `search_stories`, `get_project_info`, `list_boards`) accepts an optional\n`project_key` argument that overrides the default for that call. Use `list_projects` to discover\navailable keys. If no `project_key` is passed and no default is configured, the tool returns a clear\nerror rather than guessing.\n\n---\n\n## Burndown\n\nAn MCP server can't return a rendered chart image, but `get_sprint_burndown` returns the underlying\n**data**: a reliable computed summary (committed / completed / remaining story points and issue\ncounts by status, derived from the sprint's issues) plus a best-effort raw GreenHopper burndown\ntime-series (`burndown_chart_raw`) when that internal endpoint is available. The AI can summarize\nprogress, flag scope changes, and describe the burndown from this data. Story points are read from\n`JIRA_STORY_POINTS_FIELD`.\n\n---\n\n## Development\n\n```bash\nnpm install\nnpm run dev      # ts-node src/index.ts\nnpm run build    # tsc -> dist/\nnpm start        # node dist/index.js\n```\n\nProject layout:\n\n```\nsrc/\n├── index.ts            # bootstrap (stdio transport)\n├── config.ts           # env / config-file loading + validation\n├── logger.ts           # stderr logger\n├── jira/\n│   ├── client.ts       # axios clients (core / agile / greenhopper) + browseUrl\n│   └── errors.ts       # error mapping + ok()/fail() result helpers\n└── tools/\n    ├── index.ts        # registerAllTools()\n    ├── shared.ts       # registerTool wrapper, annotations, confirm + project helpers\n    └── *.ts            # one file per tool\n```\n\n---\n\n## Releasing\n\nReleases are automated by [`.github/workflows/release.yml`](.github/workflows/release.yml): pushing a\n`v*` tag builds the package, publishes it to npm (with provenance), and creates a GitHub Release with\nauto-generated notes.\n\n**One-time setup:** add a repo secret `NPM_TOKEN` (an npm *Automation* access token) under\n**Settings → Secrets and variables → Actions**.\n\n**Cut a release:**\n\n```bash\nnpm version patch   # or minor / major — bumps package.json and creates the tag\ngit push --follow-tags\n```\n\nThe workflow verifies the tag matches `package.json` before publishing.\n\n---\n\n## License\n\n[MIT](LICENSE) © Sina Haseli\n","readmeFilename":"README.md","_rev":"1-0d01a0dcf635aa20ba4e664b43cb84ab"}