{"id":50297720,"url":"https://github.com/softspark/jira-mcp","last_synced_at":"2026-05-28T10:03:53.556Z","repository":{"id":351288420,"uuid":"1209428886","full_name":"softspark/jira-mcp","owner":"softspark","description":"Model Context Protocol server for Jira - lets Claude and other AI clients read, update, and comment on tasks across multiple Jira instances, with ADF formatting and local caching","archived":false,"fork":false,"pushed_at":"2026-05-12T20:08:27.000Z","size":1013,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T22:11:16.896Z","etag":null,"topics":["adf","atlassian-document-format","automation","claude-code","cli","jira-api","llm-tools","mcp-server","nodejs","productivity"],"latest_commit_sha":null,"homepage":"https://softspark.eu/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/softspark.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["softspark"],"custom":["https://softspark.eu"]}},"created_at":"2026-04-13T12:22:24.000Z","updated_at":"2026-05-12T20:08:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/softspark/jira-mcp","commit_stats":null,"previous_names":["softspark/jira-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/softspark/jira-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softspark%2Fjira-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softspark%2Fjira-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softspark%2Fjira-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softspark%2Fjira-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/softspark","download_url":"https://codeload.github.com/softspark/jira-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/softspark%2Fjira-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33603475,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adf","atlassian-document-format","automation","claude-code","cli","jira-api","llm-tools","mcp-server","nodejs","productivity"],"created_at":"2026-05-28T10:03:49.373Z","updated_at":"2026-05-28T10:03:53.550Z","avatar_url":"https://github.com/softspark.png","language":"TypeScript","funding_links":["https://github.com/sponsors/softspark","https://softspark.eu"],"categories":[],"sub_categories":[],"readme":"# jira-mcp\n\n\u003e MCP server for Jira integration -- multi-instance routing, ADF formatting, task caching, and comment templates via the Model Context Protocol.\n\n[![CI](https://github.com/softspark/jira-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/softspark/jira-mcp/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/@softspark/jira-mcp)](https://www.npmjs.com/package/@softspark/jira-mcp)\n[![version](https://img.shields.io/badge/version-1.4.3-blue)](CHANGELOG.md)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n---\n\n## What's New in v1.5.0\n\n- **`template add bulk` CLI command** -- install per-project `monthly_admin.json` configs into `~/.softspark/jira-mcp/templates/tasks/\u003cKEY\u003e/`. Validated against `BulkConfigSchema`. `template list/show/remove` now also handle the `bulk` kind, keyed by project.\n- **`create_monthly_tasks` MCP tool** -- run all monthly bulk task configs over the protocol with `{ execute?, project? }`. Returns per-project status, summary counts, and resolved config paths. No more dropping to the CLI for monthly admin runs.\n\nSee [CHANGELOG.md](CHANGELOG.md) for full details.\n\n---\n\n## Table of Contents\n\n- [Install](#install)\n- [Configuration](#configuration)\n- [CLI Commands](#cli-commands)\n- [Available Tools](#available-tools)\n- [Comment Templates](#comment-templates)\n- [Usage with Claude Code](#usage-with-claude-code)\n- [Usage with Other MCP Clients](#usage-with-other-mcp-clients)\n- [Architecture](#architecture)\n- [Key Features](#key-features)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n- [Security](#security)\n- [License](#license)\n\n## Install\n\n```bash\nnpm install -g @softspark/jira-mcp\n# or use directly\nnpx @softspark/jira-mcp\n```\n\n## Update\n\n```bash\nnpm update -g @softspark/jira-mcp\n```\n\n## Configuration\n\n### 1. Generate an API token\n\nGo to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens) and create a token.\n\n### 2. Initialize global config\n\n```bash\njira-mcp config init\njira-mcp config set-credentials\njira-mcp config add-project\n```\n\nAll configuration lives in `~/.softspark/jira-mcp/` (created by `jira-mcp config init`). This is the standard config directory for all SoftSpark open-source tools.\n\n## CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `jira-mcp` | Start MCP server (default) |\n| `jira-mcp serve` | Start MCP server (explicit) |\n| `jira-mcp create \u003cpath\u003e` | Create tasks from config file (dry-run by default) |\n| `jira-mcp create-monthly` | Create monthly admin tasks from built-in templates |\n| `jira-mcp template add \u003ctype\u003e \u003cpath\u003e` | Install a template override from a local markdown file |\n| `jira-mcp template list [type]` | List active comment/task templates |\n| `jira-mcp template show \u003ctype\u003e \u003cid\u003e` | Show the active template file content |\n| `jira-mcp template remove \u003ctype\u003e \u003cid\u003e` | Remove a user-installed template override |\n| `jira-mcp config init` | Initialize global config at `~/.softspark/jira-mcp/` |\n| `jira-mcp config add-project \u003ckey\u003e \u003curl\u003e` | Add a Jira project to config |\n| `jira-mcp config remove-project \u003ckey\u003e` | Remove a project from config |\n| `jira-mcp config list-projects` | List all configured projects with language |\n| `jira-mcp config set-credentials` | Set API credentials |\n| `jira-mcp config set-default \u003ckey\u003e` | Set default project |\n| `jira-mcp config set-language \u003clang\u003e` | Set global default language |\n| `jira-mcp config set-project-language \u003ckey\u003e \u003clang\u003e` | Set language for a specific project |\n| `jira-mcp cache sync-workflows` | Sync workflow status transitions |\n| `jira-mcp cache sync-users` | Sync user list for reassignment |\n| `jira-mcp cache list-workflows` | Show cached workflows |\n| `jira-mcp cache list-users` | Show cached users |\n\n## Available Tools\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `sync_tasks` | Sync tasks from Jira to local cache | `project_key?`, `jql?` |\n| `read_cached_tasks` | Read tasks from cache without hitting Jira | `task_key?` |\n| `update_task_status` | Change task status via workflow transition | `task_key`, `status` |\n| `update_task` | Update existing issue fields (markdown → ADF) | `task_key`, `summary?`, `description?`, `priority?`, `labels?` |\n| `add_task_comment` | Add a markdown comment (auto-converted to ADF) | `task_key`, `comment`, `user_approved` |\n| `delete_task` | Delete a task, only when the authenticated user is the task creator | `task_key`, `user_approved` |\n| `delete_comment` | Delete a comment, only when the authenticated user is the comment author | `task_key`, `comment_id`, `user_approved` |\n| `reassign_task` | Reassign or unassign a task | `task_key`, `assignee_email?` |\n| `get_task_statuses` | Get valid workflow transitions for a task | `task_key` |\n| `get_task_details` | Get full details with description, comments, and language | `task_key` |\n| `get_project_language` | Get configured language for a project | `project_key` |\n| `log_task_time` | Log work time (`\"2h 30m\"` format, no days) | `task_key`, `time_spent`, `comment?` |\n| `get_task_time_tracking` | Get time tracking info (estimate, spent, remaining) | `task_key` |\n| `list_comment_templates` | List available comment templates | `category?` |\n| `list_task_templates` | List available task templates for `create_task` | — |\n| `add_templated_comment` | Add comment using a template or raw markdown | `task_key`, `template_id?`, `variables?`, `markdown?`, `user_approved` |\n| `create_task` | Create a new Jira issue with explicit fields or a task template | `project_key`, `summary?`, `template_id?`, `variables?`, `description?`, `assignee_email?`, `labels?`, `epic_key?` |\n| `search_tasks` | Search Jira issues with JQL (no caching) | `jql`, `max_results?`, `project_key?` |\n\n## Comment Templates\n\n8 built-in templates organized by category:\n\n| Template ID | Name | Category | Required Variables |\n|-------------|------|----------|--------------------|\n| `status-update` | Status Update | workflow | `completed`, `next_steps` |\n| `blocker-notification` | Blocker Notification | communication | `blocked_by`, `impact`, `needed_action` |\n| `handoff-transition` | Task Handoff | workflow | `from_person`, `to_person`, `context`, `remaining_work` |\n| `review-request` | Review Request | communication | `reviewer`, `summary`, `link` |\n| `sprint-update` | Sprint Update | reporting | `progress`, `risks` |\n| `bug-report` | Bug Report | development | `steps`, `expected`, `actual` |\n| `deployment-note` | Deployment Note | development | `changes`, `rollback_plan` |\n| `time-log-summary` | Time Log Summary | reporting | `duration`, `work_description` |\n\n### Using Templates\n\nExample with Claude Code:\n\n\u003e \"Add a status update to PROJ-123: completed auth module, next steps are testing, no blockers\"\n\nThe AI will use `add_templated_comment` with `template_id: \"status-update\"` automatically.\n\n### File-Backed Overrides\n\nSystem templates are shipped as markdown files. User overrides are loaded from:\n\n```text\n~/.softspark/jira-mcp/templates/comments/\n~/.softspark/jira-mcp/templates/task-templates/\n```\n\nIf a user file has the same `id` as a system template, the user file wins globally for all projects.\n\n```bash\njira-mcp template add comment ./my-status-update.md\njira-mcp template add task ./my-bug-task.md\njira-mcp template list\n```\n\n## Usage with Claude Code\n\nAdd to your Claude Code MCP configuration (`~/.claude/claude_desktop_config.json` or project-level):\n\n```json\n{\n  \"mcpServers\": {\n    \"jira\": {\n      \"command\": \"npx\",\n      \"args\": [\"@softspark/jira-mcp\"]\n    }\n  }\n}\n```\n\nConfiguration is automatically loaded from `~/.softspark/jira-mcp/`. Run `jira-mcp config init` first to set up.\n\n### AI Toolkit Rules\n\nIf you use `@softspark/ai-toolkit`, register the Jira rules so that Claude Code automatically follows project conventions (language checks, sync-first workflow, time format, etc.):\n\n```bash\nai-toolkit rules add jira-mcp --path /path/to/jira-mcp/rules/jira-mcp.md\n```\n\nOr copy `rules/jira-mcp.md` to your ai-toolkit rules directory manually. The rules file covers:\n- **Language first** -- always check project language before writing comments/descriptions\n- **Sync before read** -- cache may be stale\n- **Status transitions** -- check valid transitions before changing status\n- **Time format** -- `\"2h 30m\"`, never days\n- **All 19 MCP tools** and **20 CLI commands** reference\n\n### AI Toolkit Hooks\n\nTo require explicit user approval before Jira comment writes, inject the repo-owned hook manifest:\n\n```bash\nai-toolkit inject-hook https://raw.githubusercontent.com/softspark/jira-mcp/main/hooks/jira-mcp-hooks.json\n```\n\nThis installs a `PreToolUse` guard for `add_task_comment` and `add_templated_comment`. The hook blocks the tool call, shows the exact comment preview, and tells the agent to retry only after the user approves it with `user_approved=true`.\n\nThe MCP server still enforces `user_approved=true` at runtime, so the hook is UX guidance plus an extra safety layer rather than the only check.\n\n## Usage with Other MCP Clients\n\nAny MCP client that supports stdio transport can use this server:\n\n```json\n{\n  \"command\": \"npx\",\n  \"args\": [\"@softspark/jira-mcp\"],\n  \"transport\": \"stdio\"\n}\n```\n\nConfiguration is loaded from `~/.softspark/jira-mcp/` automatically. No environment variables needed.\n\n## Architecture\n\n```\nsrc/\n  adf/            Atlassian Document Format conversion (MD \u003c-\u003e ADF)\n  bulk/           Bulk task creator (dry-run, rate limiting, bilingual)\n  cache/          Local task, workflow, and user caching (JSON files)\n  cli/            CLI entry point and subcommand handlers\n    commands/\n      cache/      Cache management subcommands\n      config/     Config management subcommands\n      template/   File-backed template management subcommands\n      create.ts   Bulk task creation command\n      create-monthly.ts  Monthly admin task automation\n  config/         Configuration loading and Zod validation\n  connector/      Jira API client (built-in fetch, instance pool)\n  errors/         Typed error hierarchy\n  operations/     Business logic (status, comments, time tracking)\n  templates/      File-backed comment/task template loading and registries\n  tools/          MCP tool handlers (19 tools, one file per tool)\n  types/          Shared TypeScript types\n  server.ts       MCP server setup and tool registration\n  cli.ts          CLI entry point\n```\n\n## Key Features\n\n**Multi-instance routing** -- single server manages multiple Jira Cloud/Server instances. Project key determines which instance handles the request. Connectors deduplicated by URL via [InstancePool](kb/reference/architecture.md).\n\n**ADF round-trip** -- comments and descriptions use Atlassian Document Format natively. Markdown in, ADF to Jira v3 API, ADF back to readable markdown. Never loses formatting. See [ADF Reference](kb/reference/adf.md).\n\n**Local caching** -- tasks synced to `~/.softspark/jira-mcp/cache/` with atomic writes (tmp + rename). Work offline with `read_cached_tasks`, sync on demand. Workflow and user caches for status validation and assignee resolution.\n\n**File-backed templates** -- 8 built-in comment templates and built-in task templates are stored as markdown files, with global user overrides loaded from `~/.softspark/jira-mcp/templates/`. Both support `{{variable}}` interpolation and `{{#var}}...{{/var}}` conditional blocks. See [Templates Reference](kb/reference/templates.md).\n\n**Language configuration** -- global `default_language` with per-project override. Supports: pl, en, de, es, fr, pt, it, nl. `get_project_language` tool and `language` field in `get_task_details` let AI assistants write content in the correct language. See [Configuration](kb/reference/configuration.md).\n\n**Bulk task creation** -- create tasks from JSON configs with dry-run default, rate limiting, epic link discovery, assignee caching, multilingual support (8 languages), and idempotent updates. See [CLI Usage](kb/howto/cli-usage.md).\n\n**Per-instance credentials** -- different API tokens per Jira instance URL. Single-credential format still works (backward compatible). See [Configuration](kb/reference/configuration.md).\n\n**Supply chain protection** -- `ignore-scripts=true`, no axios, no dynamic requires. Self-contained 535KB bundle, 1 runtime dep (commander).\n\n**Typed error hierarchy** -- 20 error classes with machine-readable codes. Every tool returns structured `{ success, error, code }` responses. No stack traces leak to MCP clients.\n\n**Strict TypeScript** -- `strict: true`, no `any`, `readonly` interfaces, Zod validation at all boundaries, 587 tests across 60 test files. Self-contained 535KB package.\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Architecture](kb/reference/architecture.md) | System design and module overview |\n| [API Reference](kb/reference/api.md) | All 19 MCP tools with schemas |\n| [Configuration](kb/reference/configuration.md) | Config files, env vars, multi-instance |\n| [ADF Format](kb/reference/adf.md) | Atlassian Document Format conversion |\n| [Caching](kb/reference/caching.md) | Task, workflow, and user caching |\n| [Templates](kb/reference/templates.md) | Comment and task templates |\n| [Setup Guide](kb/howto/setup.md) | Getting started step-by-step |\n| [CLI Usage](kb/howto/cli-usage.md) | Complete CLI reference |\n| [Multi-Instance](kb/howto/multi-instance.md) | Multiple Jira instances |\n| [Troubleshooting](kb/troubleshooting/common-issues.md) | Common issues and fixes |\n\n## Contributing\n\nSee [CONTRIBUTING.md](.github/CONTRIBUTING.md).\n\n## Security\n\nSee [SECURITY.md](SECURITY.md).\n\n## License\n\n[MIT](LICENSE) -- SoftSpark\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md).\n\n---\n\nBuilt at [SoftSpark](https://softspark.eu). Designed for AI-assisted Jira workflows.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftspark%2Fjira-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoftspark%2Fjira-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoftspark%2Fjira-mcp/lists"}