jira-mcp

MCP server for Jira integration -- multi-instance routing, ADF formatting, task caching, and comment templates via the Model Context Protocol.

What's New in v1.16.1

• A rejected call says so. Every argument check used to answer UNKNOWN_ERROR, which reads as "something broke". They now answer INVALID_INPUT: a missing argument, template_id together with markdown, an update with nothing to change, a time like 2d, a malformed Tempo date or group_by. Nothing reaches Jira, and the message names what to pass.
• A template rendered without a required variable answers TEMPLATE_MISSING_VAR, as the API reference always said it did.
• If a client matched on UNKNOWN_ERROR to detect a bad call, match on the new codes instead. UNKNOWN_ERROR is left for failures nobody anticipated.
• From 1.16.0: creator and reporter on every task read. search_tasks, get_task_details, sync_tasks and read_cached_tasks now say who filed an issue and who it is reported by. Before, neither field reached a response, so "who raised this bug" had no answer.
• Both hold the email, or the display name when Atlassian privacy settings hide the email, and null when Jira returns none. To filter by them, use JQL: creator = "[email protected]" or reporter = currentUser().
• An existing task cache keeps loading. Rows cached before the upgrade read null for both fields until the next sync_tasks.
• Released together with @softspark/confluence-mcp under one version. See the changelog.

Table of Contents

• Install
• Configuration
• CLI Commands
• Available Tools
• Comment Templates
• Usage with Claude Code
• Usage with Other MCP Clients
• Architecture
• Key Features
• Documentation
• Contributing
• Security
• License

Install

npm install -g @softspark/jira-mcp
# or use directly
npx @softspark/jira-mcp

Update

npm update -g @softspark/jira-mcp

Configuration

1. Generate an API token

Go to Atlassian API Tokens and create a token.

2. Initialize global config

jira-mcp config init
jira-mcp config set-credentials
jira-mcp config add-project

All configuration lives in ~/.softspark/jira-mcp/ (created by jira-mcp config init). This is the standard config directory for all SoftSpark open-source tools.

3. Tempo (optional)

If the site runs Tempo Timesheets, create a Tempo API token (Tempo > Settings > API Integration) and store it next to the Jira credential:

jira-mcp config set-tempo-token --token TEMPO_TOKEN

That unlocks search_tempo_worklogs and get_tempo_report. Without it every other tool works as before. Sites pinned to a Tempo region set tempo_api_url in config.json (https://api.eu.tempo.io/4 or https://api.us.tempo.io/4).

CLI Commands

| Command | Description | |---------|-------------| | jira-mcp | Start MCP server (default) | | jira-mcp serve | Start MCP server (explicit) | | jira-mcp audit [--json\|--sarif] | Audit local permissions and shipped hook ownership without contacting Jira | | jira-mcp create <path> | Create tasks from config file (dry-run by default) | | jira-mcp create-monthly | Create monthly admin tasks from built-in templates | | jira-mcp template add <type> <path> | Install a template override from a local markdown file | | jira-mcp template list [type] | List active comment/task templates | | jira-mcp template show <type> <id> | Show the active template file content | | jira-mcp template remove <type> <id> | Remove a user-installed template override | | jira-mcp template list-locales | List languages with shipped template translations | | jira-mcp template install-locale <lang> [--keep-english] | Install the translated comment templates for a language | | jira-mcp config init | Initialize global config at ~/.softspark/jira-mcp/ | | jira-mcp config add-project <key> <url> | Add a Jira project to config | | jira-mcp config remove-project <key> | Remove a project from config | | jira-mcp config list-projects | List all configured projects with language | | jira-mcp config set-credentials | Set API credentials | | jira-mcp config set-tempo-token | Set the Tempo API token (default site or --url <jira-url>) | | jira-mcp config set-default <key> | Set default project | | jira-mcp config set-language <lang> | Set global default language | | jira-mcp config set-project-language <key> <lang> | Set language for a specific project | | jira-mcp cache sync-workflows | Sync workflow status transitions | | jira-mcp cache sync-users | Sync user list for reassignment | | jira-mcp cache list-workflows | Show cached workflows | | jira-mcp cache list-users | Show cached users |

Available Tools

| Tool | Description | Key Parameters | |------|-------------|----------------| | sync_tasks | Sync tasks from Jira to local cache | project_key?, jql? | | read_cached_tasks | Read tasks from cache without hitting Jira | task_key? | | update_task_status | Change task status via workflow transition | task_key, status | | update_task | Update existing issue fields (markdown → ADF) | task_key, summary?, description?, priority?, labels?, original_estimate?, remaining_estimate? | | add_task_comment | Add a markdown comment (auto-converted to ADF) | task_key, comment, user_approved | | delete_task | Delete a task, only when the authenticated user is the task creator | task_key, user_approved | | delete_comment | Delete a comment, only when the authenticated user is the comment author | task_key, comment_id, user_approved | | reassign_task | Reassign or unassign a task | task_key, assignee_email? | | get_task_statuses | Get valid workflow transitions for a task | task_key | | get_task_details | Get full details with description, comments, and language | task_key | | get_project_language | Get configured language for a project | project_key | | log_task_time | Log work time ("2h 30m" format, no days) | task_key, time_spent, comment? | | get_task_time_tracking | Get time tracking info (estimate, spent, remaining) | task_key | | list_comment_templates | List available comment templates | category? | | list_task_templates | List available task templates for create_task | — | | add_templated_comment | Add comment using a template or raw markdown | task_key, template_id?, variables?, markdown?, user_approved | | 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?, parent_key?, original_estimate? | | search_tasks | Search Jira issues with JQL (no caching) | jql, max_results?, project_key? | | search_tempo_worklogs | List Tempo worklogs in a date range, issue keys and user names resolved | from, to, project_key?, task_key?, user_email?, limit? | | get_tempo_report | Sum Tempo hours by project, user and/or task | from, to, group_by?, project_key?, task_key?, user_email? |

Comment Templates

8 built-in templates organized by category:

| Template ID | Name | Category | Required Variables | |-------------|------|----------|--------------------| | status-update | Status Update | workflow | completed, next_steps | | blocker-notification | Blocker Notification | communication | blocked_by, impact, needed_action | | handoff-transition | Task Handoff | workflow | from_person, to_person, context, remaining_work | | review-request | Review Request | communication | reviewer, summary, link | | sprint-update | Sprint Update | reporting | progress, risks | | bug-report | Bug Report | development | steps, expected, actual | | deployment-note | Deployment Note | development | changes, rollback_plan | | time-log-summary | Time Log Summary | reporting | duration, work_description |

Using Templates

Example with Claude Code:

"Add a status update to PROJ-123: completed auth module, next steps are testing, no blockers"

The AI will use add_templated_comment with template_id: "status-update" automatically.

File-Backed Overrides

System templates are shipped as markdown files. User overrides are loaded from:

~/.softspark/jira-mcp/templates/comments/
~/.softspark/jira-mcp/templates/task-templates/

If a user file has the same id as a system template, the user file wins globally for all projects.

jira-mcp template add comment ./my-status-update.md
jira-mcp template add task ./my-bug-task.md
jira-mcp template list

Translated templates

The shipped templates are English, and a template cannot pick a language at render time: its headings are fixed text in the body. On a project configured for another language, add_templated_comment would post an English comment and break the language-first rule.

The package ships translations under templates-system/locales/<lang>/comments/, installed as overrides:

jira-mcp template list-locales
jira-mcp template install-locale pl
jira-mcp template install-locale pl --keep-english   # installs with several project languages

Each translation keeps the English id and the English variable names of the template it replaces, so it overrides cleanly and no existing add_templated_comment call breaks. Only the prose changes.

Installing a language makes it the default for every project, because the choice cannot be made per call. --keep-english additionally installs the originals as <id>-en, which is what you want when some projects are English and some are not.

Restart your MCP client afterwards. The template catalog is read once at server startup, so a running server keeps serving the templates it loaded and the next templated comment silently renders the old version.

Usage with Claude Code

Add to your Claude Code MCP configuration (~/.claude/claude_desktop_config.json or project-level):

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["@softspark/jira-mcp"]
    }
  }
}

Configuration is automatically loaded from ~/.softspark/jira-mcp/. Run jira-mcp config init first to set up.

AI Toolkit Rules

If 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.):

ai-toolkit add-rule https://raw.githubusercontent.com/softspark/jira-mcp/main/rules/jira-mcp.md
ai-toolkit update

The URL form is re-fetched on every ai-toolkit update, so the rules follow releases. A local path works too (ai-toolkit add-rule /path/to/jira-mcp/rules/jira-mcp.md) but stays frozen at that copy. The rules file covers:

• Language first -- always check project language before writing comments/descriptions
• Sync before read -- cache may be stale
• Status transitions -- check valid transitions before changing status
• Time format -- "2h 30m", never days
• All 21 MCP tools and 24 CLI commands reference

AI Toolkit Hooks

To require explicit user approval before Jira comment writes, inject the repo-owned hook manifest:

ai-toolkit inject-hook https://raw.githubusercontent.com/softspark/jira-mcp/main/hooks/jira-mcp-hooks.json

This 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.

The 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.

Usage with Other MCP Clients

Any MCP client that supports stdio transport can use this server:

{
  "command": "npx",
  "args": ["@softspark/jira-mcp"],
  "transport": "stdio"
}

Configuration is loaded from ~/.softspark/jira-mcp/ automatically. No environment variables needed.

Architecture

src/
  adf/            Atlassian Document Format conversion (MD <-> ADF)
  bulk/           Bulk task creator (dry-run, rate limiting, bilingual)
  cache/          Local task, workflow, and user caching (JSON files)
  cli/            CLI entry point and subcommand handlers
    commands/
      cache/      Cache management subcommands
      config/     Config management subcommands
      template/   File-backed template management subcommands
      create.ts   Bulk task creation command
      create-monthly.ts  Monthly admin task automation
  config/         Configuration loading and Zod validation
  connector/      Jira and Tempo API clients (built-in fetch, instance pool)
  errors/         Typed error hierarchy
  operations/     Business logic (status, comments, time tracking, Tempo reports)
  templates/      File-backed comment/task template loading and registries
  tools/          MCP tool handlers (21 tools, one file per tool)
  types/          Shared TypeScript types
  server.ts       MCP server setup and tool registration
  cli.ts          CLI entry point

Key Features

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.

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.

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.

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.

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.

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.

Per-instance credentials -- different API tokens per Jira instance URL. Single-credential format still works (backward compatible). See Configuration.

Tempo worklogs and reports -- search_tempo_worklogs and get_tempo_report read Tempo Timesheets (Cloud REST API v4) for hours per project, user or task over a date range, with Tempo's numeric ids resolved to issue keys and names through Jira. Needs a Tempo API token (jira-mcp config set-tempo-token); nothing else depends on it. See API Reference.

Supply chain protection -- ignore-scripts=true, no axios, no dynamic requires. Self-contained 561KB library bundle, 1 runtime dep (commander).

Typed error hierarchy -- 32 error classes with machine-readable codes. Every tool returns structured { success, error, code } responses. No stack traces leak to MCP clients.

Strict TypeScript -- strict: true, no any, readonly interfaces, Zod validation at all boundaries, 1109 tests across 86 test files.

Documentation

| Document | Description | |----------|-------------| | Architecture | System design and module overview | | Local audit | JSON/SARIF formats, filesystem checks and hook permissions | | API Reference | All 21 MCP tools with schemas | | Configuration | Config files, env vars, multi-instance | | ADF Format | Atlassian Document Format conversion | | Caching | Task, workflow, and user caching | | Templates | Comment and task templates | | Setup Guide | Getting started step-by-step | | CLI Usage | Complete CLI reference | | Multi-Instance | Multiple Jira instances | | Troubleshooting | Common issues and fixes |

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

Apache License 2.0 -- see LICENSE and NOTICE. SoftSpark.

Fork it, modify it, ship it commercially. Three things the licence asks in return:

• Keep the attribution. Redistributions must carry the contents of NOTICE (§4d) -- project name, copyright and source URL.
• Say what you changed. Modified files must carry a prominent notice stating that you changed them (§4b).
• Names are not included. No rights to the "jira-mcp" or "SoftSpark" names or marks (§6).

The published bundles are minified, so the source headers do not survive into dist/. Attribution reaches consumers through a build banner instead -- the first comment in dist/index.js and dist/cli.js.

Releases up to and including v1.6.0 were published under MIT and stay available under MIT; the change applies going forward and revokes nothing already granted.

Changelog

See CHANGELOG.md.

Built at SoftSpark. Designed for AI-assisted Jira workflows.