·

Jira MCP với Gemini CLI

Cài đặt Jira MCP trong Gemini CLI để AI agent có thể đọc và cập nhật issue, sprint và board ngay trong trình soạn thảo.

Gemini CLI là công cụ dòng lệnh chính chủ của Google để chạy Gemini như một coding agent trong terminal, hỗ trợ MCP (Model Context Protocol) — chuẩn mở cho phép agent gọi các "tool" bên ngoài (API, database, hệ thống quản lý ticket...) một cách có kiểm soát, thay vì chỉ trả lời dựa trên dữ liệu huấn luyện sẵn. Khi bạn gắn một Jira MCP server vào Gemini CLI, agent có thể tra cứu issue, cập nhật trạng thái, quản lý sprint và tự động hoá các tác vụ triage lặp đi lặp lại — tất cả trong cùng một phiên terminal đang code. Bài này hướng dẫn cấu hình cụ thể trong settings.json, các prompt mẫu để truy vấn/cập nhật dữ liệu Jira, một ví dụ triage bug tự động đầy đủ, và cách hành vi của Gemini CLI khác với Claude Code khi cùng dùng một Jira MCP server.

Cài đặt và Kết nối Jira MCP vào Gemini CLI

Gemini CLI đọc cấu hình MCP server từ key mcpServers trong file settings.json, có thể đặt ở ba cấp: project (.gemini/settings.json trong repo, chỉ áp dụng cho project đó), user (~/.gemini/settings.json, áp dụng toàn máy), hoặc system. Với Jira, cách phổ biến nhất vẫn là self-host server community mcp-atlassian (gói Python của sooperset, giao tiếp REST API qua email + API token hoặc PAT), chạy qua uvx để không cần cài đặt thủ công.

Chuẩn bị credential

Lấy API token tại Atlassian ID → Security → API tokens (với Jira Cloud), hoặc Personal Access Token nếu công ty dùng Jira Server/Data Center on-prem. Lưu vào biến môi trường, không hardcode trực tiếp vào settings.json sẽ commit lên git:

export JIRA_URL="https://your-domain.atlassian.net"
export JIRA_USERNAME="you@company.com"
export JIRA_API_TOKEN="ATxxxxxxxxxxxxxxxxxxxxxxxxxx"

Khai báo trong .gemini/settings.json

{
  "mcpServers": {
    "jira": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "JIRA_URL": "$JIRA_URL",
        "JIRA_USERNAME": "$JIRA_USERNAME",
        "JIRA_API_TOKEN": "$JIRA_API_TOKEN"
      },
      "timeout": 15000,
      "trust": false
    }
  }
}

Trường trust: false (mặc định) khiến Gemini CLI hỏi xác nhận mỗi khi agent gọi một tool ghi (write) từ server này lần đầu trong phiên — nên giữ false cho Jira vì đây là hệ thống production, không nên auto-approve mù. Nếu muốn giới hạn kỹ hơn, dùng thêm includeTools/excludeTools để chỉ expose một tập tool con:

{
  "mcpServers": {
    "jira": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": { "JIRA_URL": "$JIRA_URL", "JIRA_USERNAME": "$JIRA_USERNAME", "JIRA_API_TOKEN": "$JIRA_API_TOKEN" },
      "includeTools": ["jira_search", "jira_get_issue", "jira_add_comment", "jira_transition_issue"]
    }
  }
}

Kết nối server remote qua OAuth (Atlassian Remote MCP)

Nếu dùng Atlassian Remote MCP Server chính chủ (chạy trên cloud Atlassian, xác thực OAuth), khai báo dạng httpUrl thay vì command:

{
  "mcpServers": {
    "jira-remote": {
      "httpUrl": "https://mcp.atlassian.com/v1/sse",
      "oauth": { "enabled": true }
    }
  }
}

Lần chạy đầu, Gemini CLI mở browser để bạn đăng nhập và cấp quyền; token sau đó lưu cục bộ và tự refresh.

Kiểm tra kết nối

Trong phiên gemini, gõ:

/mcp list

để xem trạng thái từng server (connected/disconnected/needs auth) và danh sách tool mà nó expose. Gõ /mcp desc jira để xem mô tả chi tiết từng tool nếu cần debug prompt không gọi đúng tool mong muốn.

Mẹo: Đặt trust: false cho server Jira trong mọi môi trường trừ máy cá nhân bạn hoàn toàn tin tưởng workflow — việc phải xác nhận thủ công lần gọi tool ghi đầu tiên mỗi phiên là một lớp phòng vệ rẻ, tránh trường hợp một prompt mơ hồ khiến agent transition/close issue ngoài ý muốn.

Truy vấn Sprint, Board và Issue từ Gemini CLI

Sau khi server connected, bạn ra lệnh bằng ngôn ngữ tự nhiên, Gemini CLI sẽ tự chọn tool và tham số (thường dịch sang JQL — Jira Query Language — phía dưới) mà không cần bạn nhớ cú pháp.

Truy vấn issue theo điều kiện

Tìm issue trong project "PLAT" đang "In Progress", assign cho tôi,
priority từ Medium trở lên. Kèm sprint hiện tại của mỗi issue.

Agent gọi tool search với JQL tương đương project = PLAT AND status = "In Progress" AND assignee = currentUser() AND priority in (Medium, High, Highest).

Lấy thông tin sprint và board

Sprint đang active của board "PLAT Sprint Board" có bao nhiêu issue,
bao nhiêu issue chưa estimate, và tổng story points còn lại?

Cập nhật trạng thái và comment

Chuyển PLAT-482 sang "In Review", thêm comment:
"Đã push code, PR: github.com/org/repo/pull/213. Cần review trước 5h chiều."

Do trust: false, Gemini CLI sẽ hiện prompt xác nhận trước khi gọi jira_transition_issue lần đầu trong phiên — bạn duyệt một lần, các lệnh ghi tiếp theo trong cùng phiên (tuỳ cấu hình) có thể không hỏi lại.

Kết hợp dữ liệu Jira với code trong repo

Đọc PLAT-490 rồi tìm trong repo hiện tại các file liên quan đến
"payment retry logic" được mô tả trong issue. Tóm tắt gợi ý fix.

Đây là điểm mạnh thực sự của MCP so với việc mở tab Jira riêng: agent vừa có context code trong working directory, vừa có context ticket cùng lúc trong một lượt suy luận.

Mẹo: Khi hỏi số liệu tổng hợp (velocity, tổng story points, số issue chưa estimate), luôn yêu cầu agent liệt kê rõ issue key đã dùng để tính — Jira MCP không có tool tính tổng sẵn, agent phải tự cộng dựa trên danh sách issue lấy về, và dễ tính sai nếu dữ liệu bị phân trang mà bạn không kiểm tra lại.

Ví dụ Thực tế: Tự động Triage và Gắn Label cho Bug trong Gemini CLI

Đây là workflow thực tế nhiều team dùng hàng ngày: bug mới report vào backlog thiếu label, thiếu priority, thiếu component — Gemini CLI có thể đọc description, gợi ý phân loại, và áp dụng trực tiếp.

Prompt triage đầy đủ

Lấy tất cả issue type "Bug" trong project "PLAT" đang ở status "Backlog"
và chưa có label nào. Với mỗi issue:
1. Đọc summary và description.
2. Gợi ý priority (Highest/High/Medium/Low) dựa trên mức độ ảnh hưởng
   được mô tả (crash, mất dữ liệu = Highest/High; UI lệch nhẹ = Low).
3. Gợi ý 1-2 label phù hợp trong bộ: frontend, backend, api, database,
   performance, security.
4. Gợi ý component nếu mô tả có nhắc tên module cụ thể.
Trình bày dạng bảng: Issue key | Summary | Priority đề xuất | Label đề xuất |
Component đề xuất | Lý do ngắn.

Agent xử lý ra sao

Gemini CLI gọi tool search theo JQL project = PLAT AND issuetype = Bug AND status = Backlog AND labels is EMPTY, sau đó với từng issue trả về, nó đọc field description (thường ở dạng Atlassian Document Format được server MCP convert sang plain text/markdown) và tự suy luận priority/label — đây là suy luận ngôn ngữ tự nhiên của agent, không phải business rule cứng trong Jira. Kết quả là bảng gợi ý, bạn nên review trước khi cho apply.

Áp dụng sau khi duyệt

Với 5 issue đầu trong bảng trên mà tôi đánh dấu "OK", hãy gắn priority
và label đã đề xuất, đồng thời thêm comment: "Auto-triaged by AI agent,
vui lòng review lại nếu priority/label chưa chính xác."

Tách rõ bước "đề xuất" và bước "áp dụng" giúp bạn kiểm soát được sai sót của agent trước khi dữ liệu thật trong Jira bị thay đổi hàng loạt.

Mẹo: Luôn thêm comment kiểu "Auto-triaged by AI agent" khi để agent tự gắn label/priority hàng loạt — giúp đồng nghiệp nhận biết đây là gợi ý máy, không phải quyết định cuối của người report hay lead, và biết cần double-check khi thấy bất thường.

So sánh Kết quả Jira MCP giữa Gemini CLI và Claude Code

Cùng một Jira MCP server (mcp-atlassian hoặc Atlassian Remote MCP) có thể được gắn vào cả Gemini CLI và Claude Code, nhưng hành vi agent sử dụng tool không giống nhau hoàn toàn.

Cách chọn tool và số lượt gọi

Với các prompt phức tạp có nhiều bước (ví dụ triage hàng loạt), cả hai đều có khả năng chia nhỏ thành chuỗi tool call, nhưng số lượt gọi tool cụ thể và cách agent tóm tắt kết quả trung gian có thể khác nhau giữa hai model — nên đừng giả định output giống nhau 100% khi đổi agent, dù cùng server MCP và cùng prompt.

Cơ chế xác nhận trước khi ghi dữ liệu

Gemini CLI có cờ trust cấu hình theo từng MCP server, mặc định yêu cầu xác nhận tool call đầu tiên. Claude Code có cơ chế permission riêng (approve tool theo pattern, hoặc --dangerously-skip-permissions khi cần tự động hoàn toàn trong CI). Về bản chất cả hai đều hướng tới "human-in-the-loop" cho hành động ghi, nhưng cấu hình và trải nghiệm hỏi-xác nhận khác nhau — nếu chuyển đổi qua lại giữa hai công cụ trong team, nên thống nhất rõ mức độ tự động cho phép ở từng công cụ để tránh một agent auto-approve còn agent khác chặn lại gây khó hiểu.

Format output và khả năng đọc bảng lớn

Cả hai đều render bảng markdown trong terminal, nhưng khi danh sách issue dài (backlog vài trăm issue), agent có thể tự tóm tắt/cắt bớt khác nhau tuỳ context window còn lại của model. Nên luôn yêu cầu rõ số lượng ("chỉ lấy 20 issue đầu", "chia thành nhiều lượt 50 issue") thay vì để agent tự quyết định cắt ở đâu.

Mẹo: Nếu team dùng cả Gemini CLI và Claude Code cho công việc Jira, viết chung một file prompt playbook (ví dụ docs/jira-mcp-prompts.md) với các prompt đã kiểm chứng — tránh tình trạng mỗi người viết prompt khác nhau cho cùng tác vụ, dẫn đến kết quả không đồng nhất giữa các thành viên team dù cùng dùng MCP server.

Mẹo Hay

  • Luôn bắt đầu với includeTools giới hạn (chỉ search/get/comment) trước khi mở thêm quyền transition/create issue, để làm quen hành vi agent với dữ liệu thật của công ty trước khi cấp quyền rộng.
  • Dùng biến môi trường ($JIRA_API_TOKEN) trong settings.json thay vì giá trị cứng, và thêm .gemini/settings.json vào .gitignore nếu file có chứa giá trị nhạy cảm khác ngoài biến môi trường.
  • Kiểm tra lại /mcp list sau mỗi lần upgrade phiên bản mcp-atlassian hoặc đổi Remote MCP endpoint — danh sách tool có thể thay đổi và ảnh hưởng đến includeTools đã khai báo.
  • Với các tác vụ triage/report lặp lại hàng tuần, lưu prompt thành snippet có thể tái sử dụng, tránh soạn lại từ đầu mỗi lần và giảm rủi ro prompt thiếu điều kiện quan trọng (ví dụ quên lọc theo project key khi làm việc đa project).

Mẹo: Trước khi giao Jira MCP cho một thành viên mới trong team dùng Gemini CLI, hãy để họ chạy thử với một service account chỉ có quyền đọc trên một project test — quan sát cách họ ra prompt và cách agent phản hồi, trước khi cấp token có quyền ghi trên project thật.

Tiếp Jira MCP với Cursor