🚀 Jira MCP Server

Jira MCP Server là cầu nối giữa AI và Jira Cloud. Thay vì phải vào web Jira để tạo issue, tìm kiếm, cập nhật trạng thái — bạn chỉ cần nói hoặc gõ lệnh, AI sẽ làm thay.

Ví dụ:

"Tạo issue bug cho project DEV, mô tả lỗi login bị 500"
"Tìm tất cả issues đang In Progress được gán cho tôi"
"Chuyển issue DEV-123 sang Done"
"Phân tích yêu cầu này thành các task trong sprint"

✨ Tính năng (16 Tools)

📋 Quản lý Issue

Câu lệnh	Server làm
"Tạo issue mới"	Tạo issue với project, summary, type, priority, labels, assignee
"Xem issue DEV-123"	Lấy chi tiết issue (status, assignee, description ADF đẹp)
"Sửa issue DEV-123"	Cập nhật summary, description, priority, labels, assignee
"Xoá issue DEV-123"	Xoá vĩnh viễn
"Tìm issue bị lỗi"	Search bằng JQL — mạnh mẽ, linh hoạt

💬 Comments & Workflow

Câu lệnh	Server làm
"Thêm comment vào DEV-123"	Ghi comment
"Chuyển DEV-123 sang In Progress"	Chuyển trạng thái workflow

📂 Projects & Sprint

Câu lệnh	Server làm
"Liệt kê projects"	Danh sách projects
"Board nào đang có?"	Danh sách boards
"Tạo sprint mới"	Tạo sprint với tên, thời gian, mục tiêu
"Issues trong sprint 5?"	Tất cả issues trong sprint

👤 Users

Câu lệnh	Server làm
"Tìm user tên An"	Search users theo tên, email

Mô tả issue tự động render đẹp: khi bạn nhập description dạng Markdown (## heading, - bullet list), server tự động chuyển sang Atlassian Document Format (ADF) — hiển thị headings, lists, paragraphs rõ ràng trong Jira.

🛠️ Cài đặt

Yêu cầu

Python 3.10+
Tài khoản Jira Cloud (free cũng được)
Jira API Token
Git (clone project)

1. Clone & cài đặt

git clone https://github.com/rifujin123/jira-mcp.git
cd jira-mcp

# Tạo môi trường ảo
python -m venv .venv

# Kích hoạt
# Windows:
.venv\Scripts\activate
# Mac / Linux:
source .venv/bin/activate

# Cài thư viện
pip install -r requirements.txt

# Tạo file .env từ mẫu
cp .env.example .env

2. Lấy Jira API Token

Vào https://id.atlassian.com/manage/api-tokens
Click Create API token
Đặt tên (VD: "Jira MCP")
Copy token

3. Điền credentials

Sửa file .env với nội dung:

JIRA_URL=https://ten-domain.atlassian.net
JIRA_EMAIL=email-cua-ban@gmail.com
JIRA_API_TOKEN=token-vua-tao

4. Kiểm tra kết nối

# Windows:
PYTHONIOENCODING=utf-8 .venv\Scripts\python jira_client.py
# Mac / Linux:
python jira_client.py

Nếu thấy danh sách projects là OK.

🔌 Kết nối với MCP Clients

🤖 Claude Code (CLI)

Cách 1: Chạy trực tiếp từ thư mục project

claude

Nếu đang ở thư mục jira-mcp, Claude Code tự động detect file server.py. Nếu không, chạy:

claude --mcp-server "python D:/GITHUB/Jira-mcp/server.py"

Cách 2: Thêm vào config (không cần cd vào project)

Mở file:

Windows: %APPDATA%\Claude Code\settings.json
Mac: ~/Library/Application Support/Claude Code/settings.json

Thêm vào mcpServers:

{
  "mcpServers": {
    "jira": {
      "command": "python",
      "args": ["D:/GITHUB/Jira-mcp/server.py"],
      "env": {
        "JIRA_URL": "https://ten-domain.atlassian.net",
        "JIRA_EMAIL": "email-cua-ban@gmail.com",
        "JIRA_API_TOKEN": "token-cua-ban"
      }
    }
  }
}

Cách 3: Dùng uv (nhanh hơn, không cần cài thủ công)

pip install uv

{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/jira-mcp",
        "server.py"
      ],
      "env": {
        "JIRA_URL": "https://ten-domain.atlassian.net",
        "JIRA_EMAIL": "email-cua-ban@gmail.com",
        "JIRA_API_TOKEN": "token-cua-ban"
      }
    }
  }
}

🖥️ Claude Desktop App

Mở file config:

Windows: %APPDATA%\Claude\claude_desktop_config.json
Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "jira": {
      "command": "python",
      "args": ["D:/GITHUB/Jira-mcp/server.py"],
      "env": {
        "JIRA_URL": "https://ten-domain.atlassian.net",
        "JIRA_EMAIL": "email-cua-ban@gmail.com",
        "JIRA_API_TOKEN": "token-cua-ban"
      }
    }
  }
}

Sau đó Restart Claude Desktop → thấy icon cờ lê → Jira tools sẵn sàng.

📘 VS Code (Visual Studio Code)

Cài extension Claude Code hoặc dùng MCP client cho VS Code:

1. Cài Claude Code extension:

Mở VS Code
Extensions → tìm "Claude Code"
Cài đặt

2. Cấu hình trong VS Code:

File → Preferences → Settings
Tìm claude.mcpServers
Add:

{
  "jira": {
    "command": "python",
    "args": ["D:/GITHUB/Jira-mcp/server.py"],
    "env": {
      "JIRA_URL": "https://ten-domain.atlassian.net",
      "JIRA_EMAIL": "email-cua-ban@gmail.com",
      "JIRA_API_TOKEN": "token-cua-ban"
    }
  }
}

Hoặc dùng file .vscode/settings.json trong project.

⌨️ Cursor

1. Mở Cursor Settings:

File → Preferences → Cursor Settings
Tab MCP

2. Add MCP Server:

{
  "jira": {
    "command": "python",
    "args": ["D:/GITHUB/Jira-mcp/server.py"],
    "env": {
      "JIRA_URL": "https://ten-domain.atlassian.net",
      "JIRA_EMAIL": "email-cua-ban@gmail.com",
      "JIRA_API_TOKEN": "token-cua-ban"
    }
  }
}

🧰 Công cụ MCP Inspector (Test nhanh)

Dùng để test từng tool qua Web UI mà không cần AI client:

pip install "mcp[cli]"
mcp dev server.py

Mở http://localhost:5173 → thử từng tool trực quan.

📚 JQL Examples

// Tất cả issues của project DEV
project = DEV

// Issues đang In Progress, gán cho tôi
assignee = currentUser() AND status = "In Progress"

// Tìm theo từ khoá
text ~ "database error"

// Issues được tạo trong 7 ngày gần đây
created >= -7d

// Priority cao nhất
project = DEV ORDER BY priority DESC, created ASC

// Issues trong sprint cụ thể
sprint = 5

// Bugs chưa được assign
issuetype = Bug AND assignee IS NULL

🧠 Kiến trúc

Bạn ── nói ──► AI (Claude/Cursor/...) ── JSON-RPC ──► Jira MCP Server ── HTTP ──► Jira Cloud API
                                                        │
                                                        ▼
                                                16 tools sẵn sàng

Layer	Công nghệ
Transport	stdio (process-to-process)
Protocol	MCP (Model Context Protocol)
Jira SDK	atlassian-python-api
MCP SDK	FastMCP (Python)
Auth	Basic Auth (email + API token)
Description	ADF (Atlassian Document Format) — rich text

📁 Cấu trúc project

jira-mcp/
├── server.py          # ★ File chính — MCP server, 16 tools
├── jira_client.py     # JiraClient — gọi API, xử lý lỗi, ADF format
├── requirements.txt   # Thư viện cần cài
├── .env               # Credentials Jira (đã có .gitignore)
├── .env.example       # Mẫu file .env
└── README.md          # Bạn đang đọc đây

⚠️ Lỗi thường gặp

Lỗi	Nguyên nhân	Cách fix
"Authentication failed"	Sai email hoặc API token	Kiểm tra lại `.env`
"Resource not found"	Sai issue key, project key	Kiểm tra lại key
"Site temporarily unavailable"	Jira site chưa active	Vào browser kiểm tra
"Rate limit exceeded"	Gọi API quá nhanh	Chờ 1 lúc rồi thử lại
"Jira Software license"	Board/sprint không có	Nâng cấp plan hoặc bỏ qua
`cp1252` encode error	Windows terminal	Thêm `PYTHONIOENCODING=utf-8`

📄 License

MIT — tự do dùng, sửa, chia sẻ.