convez.ai
MCP ServerIntegração & APIsIntermediário
hieutv-dng

Jira MCP Server

hieutv-dng/jira-mcp-server

Integração Jira com Claude para gerenciar issues e timesheet via IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que integra Jira Server/Data Center com Claude AI, permitindo listar issues, registrar horas, atualizar e criar tickets diretamente. Suporta Claude Desktop, Cursor, Windsurf e LangChain com autenticação via Personal Access Token e detecção automática de drift entre descrições e comentários.

Instalação

$npx convez-ai hieutv-dng/jira-mcp-server

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
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Listar e filtrar issues do Jira via linguagem natural no Claude
  • Registrar horas de trabalho (timesheet) automaticamente
  • Atualizar status, assignee e labels de tickets sem sair do chat
  • Criar issues e adicionar comentários via IA
  • Auditar inconsistências entre descrições e comentários de issues

Veredito

MCP server robusto e production-ready para equipes que usam Jira Server/Data Center (não Cloud). Implementação segura com confirmação obrigatória em write operations e suporte multi-client (Claude Desktop, Cursor, HTTP remoto). Recomendado para times que querem automação de gestão de projetos dentro do fluxo de trabalho com Claude.

README

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

jira-mcp-server

MCP (Model Context Protocol) server tích hợp Jira cho Claude AI. Hỗ trợ Claude Desktop, Cursor, Windsurf, và LangChain tương tác trực tiếp với Jira Server/Data Center (không Cloud).

Thông tinGiá trị
Phiên bảnv1.4.0
Trạng tháiProduction-ready
Xác thựcPersonal Access Token (PAT)
TransportsStdio (Claude Desktop), HTTP (LangChain, remote)

Tính năng

  • 8 Tools: get_current_user, list_issues, get_issue_detail, log_work, list_worklogs, delete_worklog, update_issue, create_issue
  • Drift Detection: Cảnh báo khi description lỗi thời so với comments
  • Tool Chaining: Gợi ý hành động tiếp theo sau mỗi tool
  • Safety-First: Write operations yêu cầu xác nhận từ user
  • Markdown Output: Format AI-friendly với priority emojis, quality analysis

Bắt đầu nhanh

Yêu cầu

  • Node.js 18+
  • Jira Server/Data Center v7+ (không Cloud)
  • Personal Access Token (PAT)

Setup

  1. Clone & install:
git clone <repo-url> && cd jira-mcp-server && npm install
  1. Cấu hình .env.local:
JIRA_BASE_URL=https://jira.company.com
JIRA_PAT=<your-pat-token>
JIRA_DEFAULT_PROJECT=XYZ  # Tùy chọn
  1. Build & Run:
npm run build                                    # Stdio transport
HTTP_PORT=3000 MCP_AUTH_TOKEN=secret npm start   # HTTP transport

Share cho Team (không cần .env file)

Mỗi thành viên tự config trực tiếp trong MCP client của mình:

Claude Desktop (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "jira-mcp-server": {
      "command": "node",
      "args": ["/path/to/jira-mcp-server/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://jira.company.com",
        "JIRA_PAT": "your-personal-pat-token"
      }
    }
  }
}

Cursor/Windsurf (.cursor/mcp.json hoặc .windsurf/mcp.json):

{
  "mcpServers": {
    "jira-mcp-server": {
      "command": "node",
      "args": ["/path/to/jira-mcp-server/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://jira.company.com",
        "JIRA_PAT": "your-personal-pat-token"
      }
    }
  }
}

Lưu ý: File .env.local chỉ cần khi dev local (npm run dev). Production dùng env block trong MCP config.

Kết nối Clients

Test

npm run inspect    # MCP Inspector at http://localhost:8000

Hoặc trong Claude Desktop, thử: "Show me open issues"

Tools Reference

Tất cả write operations (log_work, update_issue, create_issue, delete_worklog) yêu cầu xác nhận từ user.

ToolMô tảChủ yếu dùng cho
get_current_userLấy thông tin user hiện tại (từ PAT)Verify PAT, biết username cho JQL
list_issuesFilter issues (assignee, status, custom JQL)Xem danh sách work items
get_issue_detailChi tiết issue + drift detectionHiểu issue trước khi làm việc
log_workGhi nhận giờ làm (yêu cầu startedAt)Timesheet, tracking
list_worklogsTổng giờ đã log (summary hoặc detail per-entry)Báo cáo timesheet, lấy worklogId
delete_worklogXoá worklog (batch + dryRun + best-effort)Sửa log nhầm
update_issueAssign, labels, transition, comment, set/clear due date, sửa summary (tiêu đề) + description (mô tả)Cập nhật trạng thái, nhãn, deadline, tiêu đề, mô tả
create_issueTạo issue (Task, Bug, Story)Tạo work item mới

Ví dụ nhanh:

# Xem issues của tôi
list_issues({ statusFilter: "open" })

# Chi tiết issue
get_issue_detail({ issueKey: "PROJ-123" })

# Log 2 tiếng hôm qua
log_work({ 
  issueKey: "PROJ-123", 
  timeSpent: "2h", 
  comment: "Fixed UI bug",
  startedAt: "2026-04-12"
})

# Tổng giờ đã log tháng này (summary)
list_worklogs({})

# Xem detail từng worklog entry (kèm worklogId)
list_worklogs({ detail: true })

# Preview trước khi xoá
delete_worklog({
  issueKey: "PROJ-123",
  worklogIds: ["12345", "12346"],
  dryRun: true
})

# Xoá thật sau khi user xác nhận
delete_worklog({
  issueKey: "PROJ-123",
  worklogIds: ["12345", "12346"]
})

# Chuyển sang Done
update_issue({ 
  issueKey: "PROJ-123", 
  transitionName: "Done", 
  resolution: "Fixed"
})

# Update due date
update_issue({
  issueKey: "PROJ-123",
  dueDate: "2026-06-30"
})

# Gỡ due date
update_issue({
  issueKey: "PROJ-123",
  dueDate: "clear"
})

# Thêm labels
update_issue({
  issueKey: "PROJ-123",
  addLabels: ["backend", "urgent"]
})

# Xoá labels
update_issue({
  issueKey: "PROJ-123",
  removeLabels: ["blocked", "needs-info"]
})

# Xoá toàn bộ labels rồi set lại
update_issue({
  issueKey: "PROJ-123",
  clearLabels: true,
  addLabels: ["triaged", "ready"]
})

# Đổi tiêu đề (summary)
update_issue({
  issueKey: "PROJ-123",
  summary: "Tiêu đề mới rõ ràng hơn"
})

# Replace toàn bộ mô tả (description, wiki markup)
update_issue({
  issueKey: "PROJ-123",
  description: "Mô tả mới\n\n* Bước 1\n* Bước 2"
})

# Combine: labels + assignee + transition
update_issue({
  issueKey: "PROJ-123",
  addLabels: ["urgent"],
  assignee: "hieutv",
  transitionName: "In Progress"
})

# Tạo task mới
create_issue({
  projectKey: "PROJ",
  issueType: "Task",
  summary: "Implement feature",
  description: "Add OAuth support",
  priority: "High"
})

Xem chi tiết: Tool Examples (nếu cần)

Development

Scripts

npm run build      # TypeScript → dist/
npm run dev        # Watch mode
npm start          # Run server (stdio or HTTP)
npm run inspect    # MCP Inspector (http://localhost:8000)

Project Structure

src/
├── index.ts              # Entry + transport selection
├── jira/
│   ├── client.ts         # REST API wrapper
│   ├── tools/            # Tool registration split theo concern
│   │   ├── index.ts              # Barrel — registerJiraTools()
│   │   ├── user-tools.ts         # get_current_user
│   │   ├── issue-tools.ts        # list_issues, get_issue_detail, update_issue
│   │   ├── issue-drift-warning.ts # Helper drift heuristic
│   │   ├── create-issue-tool.ts  # create_issue (schema lớn)
│   │   └── worklog-tools.ts      # log_work, list_worklogs, delete_worklog
│   └── formatter.ts      # AI-friendly output
├── transports/
│   ├── stdio-transport.ts
│   └── http-transport.ts # Express + Bearer auth
└── shared/utils.ts       # Error handling, chaining

Multi-Tenant Deployment

Cho phép nhiều users dùng chung một MCP server, mỗi user có credentials Jira riêng.

Architecture

Client (headers) → Nginx (:443 SSL) → Node.js (:3000) → Jira API

Client Config

Thêm X-Jira-* headers vào MCP client config:

{
  "mcpServers": {
    "jira": {
      "type": "http",
      "url": "https://mcp.company.com/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_AUTH_TOKEN>",
        "X-Jira-Base-Url": "https://jira.company.com",
        "X-Jira-Pat": "<your-personal-token>"
      }
    }
  }
}

Headers

HeaderRequiredDescription
AuthorizationYesBearer token (MCP_AUTH_TOKEN trên server)
X-Jira-Base-UrlNo*Jira server URL
X-Jira-PatNo*Personal Access Token

*Fallback to server env vars nếu không truyền headers.

Server Setup

  1. Chạy MCP server:
HTTP_PORT=3000 MCP_AUTH_TOKEN=<secret> npm start
  1. Cấu hình Nginx: Copy deploy/nginx.conf.example và sửa domain.

  2. SSL: certbot --nginx -d mcp.company.com


Documentation

Setup & Connection

Architecture & Standards

Ver o original no GitHub

Bom para

Relacionados