convez.ai
MCP ServerIntegração & APIsIntermediário
softspark

Jira MCP Server

softspark/jira-mcp

Integre Claude com Jira para gerenciar tarefas via MCP

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor Model Context Protocol para integração com Jira que permite ao Claude e outros clientes AI ler, atualizar e comentar tarefas em múltiplas instâncias Jira. Inclui formatação ADF, cache local, templates de comentários e roteamento multi-instância.

Instalação

$npx convez-ai softspark/jira-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
0
Acompanhando
1
Saúde
100%
Último commit
há 1 dia
Versão
v1.19.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Atualizar issues e tasks do Jira diretamente via Claude
  • Criar tarefas em massa com templates e configurações bulk
  • Adicionar comentários formatados em ADF em múltiplos projetos
  • Automatizar fluxos administrativos mensais de Jira

Veredito

MCP server robusto e bem mantido para quem precisa integrar Jira com Claude. Oferece recursos avançados como templates bulk, multi-instância e formatação ADF, sendo ideal para times que usam Jira e querem automação IA nativa.

README

A tradução para o português deste README ainda está na fila.

jira-mcp

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

CI npm version License: MIT


What's New in v1.5.0

  • template add bulk CLI command -- install per-project monthly_admin.json configs into ~/.softspark/jira-mcp/templates/tasks/<KEY>/. Validated against BulkConfigSchema. template list/show/remove now also handle the bulk kind, keyed by project.
  • 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.

See CHANGELOG.md for full details.


Table of Contents

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.

CLI Commands

CommandDescription
jira-mcpStart MCP server (default)
jira-mcp serveStart MCP server (explicit)
jira-mcp create <path>Create tasks from config file (dry-run by default)
jira-mcp create-monthlyCreate 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 config initInitialize 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-projectsList all configured projects with language
jira-mcp config set-credentialsSet API credentials
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-workflowsSync workflow status transitions
jira-mcp cache sync-usersSync user list for reassignment
jira-mcp cache list-workflowsShow cached workflows
jira-mcp cache list-usersShow cached users

Available Tools

ToolDescriptionKey Parameters
sync_tasksSync tasks from Jira to local cacheproject_key?, jql?
read_cached_tasksRead tasks from cache without hitting Jiratask_key?
update_task_statusChange task status via workflow transitiontask_key, status
update_taskUpdate existing issue fields (markdown → ADF)task_key, summary?, description?, priority?, labels?
add_task_commentAdd a markdown comment (auto-converted to ADF)task_key, comment, user_approved
delete_taskDelete a task, only when the authenticated user is the task creatortask_key, user_approved
delete_commentDelete a comment, only when the authenticated user is the comment authortask_key, comment_id, user_approved
reassign_taskReassign or unassign a tasktask_key, assignee_email?
get_task_statusesGet valid workflow transitions for a tasktask_key
get_task_detailsGet full details with description, comments, and languagetask_key
get_project_languageGet configured language for a projectproject_key
log_task_timeLog work time ("2h 30m" format, no days)task_key, time_spent, comment?
get_task_time_trackingGet time tracking info (estimate, spent, remaining)task_key
list_comment_templatesList available comment templatescategory?
list_task_templatesList available task templates for create_task—
add_templated_commentAdd comment using a template or raw markdowntask_key, template_id?, variables?, markdown?, user_approved
create_taskCreate a new Jira issue with explicit fields or a task templateproject_key, summary?, template_id?, variables?, description?, assignee_email?, labels?, epic_key?
search_tasksSearch Jira issues with JQL (no caching)jql, max_results?, project_key?

Comment Templates

8 built-in templates organized by category:

Template IDNameCategoryRequired Variables
status-updateStatus Updateworkflowcompleted, next_steps
blocker-notificationBlocker Notificationcommunicationblocked_by, impact, needed_action
handoff-transitionTask Handoffworkflowfrom_person, to_person, context, remaining_work
review-requestReview Requestcommunicationreviewer, summary, link
sprint-updateSprint Updatereportingprogress, risks
bug-reportBug Reportdevelopmentsteps, expected, actual
deployment-noteDeployment Notedevelopmentchanges, rollback_plan
time-log-summaryTime Log Summaryreportingduration, 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

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 rules add jira-mcp --path /path/to/jira-mcp/rules/jira-mcp.md

Or copy rules/jira-mcp.md to your ai-toolkit rules directory manually. 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 19 MCP tools and 20 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 API client (built-in fetch, instance pool)
  errors/         Typed error hierarchy
  operations/     Business logic (status, comments, time tracking)
  templates/      File-backed comment/task template loading and registries
  tools/          MCP tool handlers (19 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.

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

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.

Strict TypeScript -- strict: true, no any, readonly interfaces, Zod validation at all boundaries, 587 tests across 60 test files. Self-contained 535KB package.

Documentation

DocumentDescription
ArchitectureSystem design and module overview
API ReferenceAll 19 MCP tools with schemas
ConfigurationConfig files, env vars, multi-instance
ADF FormatAtlassian Document Format conversion
CachingTask, workflow, and user caching
TemplatesComment and task templates
Setup GuideGetting started step-by-step
CLI UsageComplete CLI reference
Multi-InstanceMultiple Jira instances
TroubleshootingCommon issues and fixes

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

MIT -- SoftSpark

Changelog

See CHANGELOG.md.


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

Ver o original no GitHub

Bom para

Relacionados