Jira MCP Server
hieutv-dng/jira-mcp-server
Integração Jira com Claude para gerenciar issues e timesheet via IA
Ver no GitHubServidor 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-server1 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
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 tin | Giá trị |
|---|---|
| Phiên bản | v1.4.0 |
| Trạng thái | Production-ready |
| Xác thực | Personal Access Token (PAT) |
| Transports | Stdio (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
- Clone & install:
git clone <repo-url> && cd jira-mcp-server && npm install
- 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
- 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.localchỉ cần khi dev local (npm run dev). Production dùngenvblock trong MCP config.
Kết nối Clients
- Claude Desktop: Xem claude-desktop-setup.md
- Cursor/Windsurf: Xem Connection Guide
- LangChain/Remote: Xem http-api-reference.md
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.
| Tool | Mô tả | Chủ yếu dùng cho |
|---|---|---|
| get_current_user | Lấy thông tin user hiện tại (từ PAT) | Verify PAT, biết username cho JQL |
| list_issues | Filter issues (assignee, status, custom JQL) | Xem danh sách work items |
| get_issue_detail | Chi tiết issue + drift detection | Hiểu issue trước khi làm việc |
| log_work | Ghi nhận giờ làm (yêu cầu startedAt) | Timesheet, tracking |
| list_worklogs | Tổng giờ đã log (summary hoặc detail per-entry) | Báo cáo timesheet, lấy worklogId |
| delete_worklog | Xoá worklog (batch + dryRun + best-effort) | Sửa log nhầm |
| update_issue | Assign, 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_issue | Tạ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
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer token (MCP_AUTH_TOKEN trên server) |
X-Jira-Base-Url | No* | Jira server URL |
X-Jira-Pat | No* | Personal Access Token |
*Fallback to server env vars nếu không truyền headers.
Server Setup
- Chạy MCP server:
HTTP_PORT=3000 MCP_AUTH_TOKEN=<secret> npm start
-
Cấu hình Nginx: Copy
deploy/nginx.conf.examplevà sửa domain. -
SSL:
certbot --nginx -d mcp.company.com
Documentation
Setup & Connection
- Connection Guide — Stdio vs HTTP
- Claude Desktop
- Cursor
- Windsurf
- LangChain
- HTTP API Reference