Jira MCP Server

將 Jira Data Center 操作封裝為 MCP (Model Context Protocol) 工具，讓 AI 助手能直接操作 Jira。

特色

• 使用 Streamable HTTP 傳輸，支援多 session 並行
• 純 JavaScript (CommonJS)，無 TypeScript、無建置步驟
• 所有模組皆採用 Factory Function + Dependency Injection，方便測試
• 零外部測試框架，使用 Node.js 22 內建 node:test + node:assert

需求

• Node.js >= 22
• Jira Data Center（REST API v2）

快速開始

1. 安裝依賴

npm install

2. 設定環境變數

複製 .env.example 為 .env 並填入：

JIRA_URL=https://your-jira-server.com
JIRA_USERNAME=your-username
JIRA_PASSWORD='your-password'

變數	說明
JIRA_URL	Jira 伺服器 URL（結尾斜線會自動移除）
JIRA_USERNAME	Jira 登入帳號
JIRA_PASSWORD	Jira 登入密碼（密碼含 $ 時用單引號包裹）

伺服器在缺少任一變數時會立即結束並提示錯誤。

3. 啟動伺服器

npm start

伺服器啟動於 http://localhost:55522/mcp。

MCP 工具一覽

工具	說明
jira_get_projects	列出所有 Jira 專案
jira_create_issue	建立新工作單（支援 Epic Link、Implementer 等自訂欄位）
jira_get_issue	取得工作單詳細資訊
jira_update_issue	更新工作單欄位
jira_search_issues	用 JQL 搜尋 Issues
jira_transition_issue	變更工作單狀態（如：In Progress、Done）
jira_add_comment	對工作單新增留言
jira_get_my_issues	取得目前登入者的未完成工作單
jira_list_fields	列出所有欄位（用於查詢 custom field ID）

自訂欄位對應

欄位 ID	語義名稱	格式
customfield_10108	Start Date (Gantt)	YYYY-MM-DDT00:00:00.000+0800
customfield_10109	End Date (Gantt)	YYYY-MM-DDT23:59:00.000+0800
customfield_10101	Epic Link	Issue Key（如 P26-10）
customfield_10111	Implementer	{ name: "username" }

專案結構

jira-mcp-server.js          # 入口點：loadEnv → createConfig → createJiraClient → main()
src/
  load-env.js                # .env 檔案解析
  config.js                  # 環境變數驗證，產生 config 物件
  jira-client.js             # HTTP client（Basic Auth，支援自簽憑證）
  tool-definitions.js        # 9 個工具的 JSON Schema 定義
  tool-handlers.js           # 工具實作邏輯 + 自訂欄位常數
  server.js                  # Express + MCP Server 設定
test/
  *.test.js                  # 對應每個模組的測試

測試

npm test

在 AI 助手中使用

先啟動伺服器（npm start），再依據需求選擇合適的設定層級。

Claude Code

Claude Code 支援三種 MCP 設定層級，優先順序為 local > project > user：

層級	檔案位置	共享	適用情境
user	~/.claude.json	否	個人常用，所有專案皆可使用
local（預設）	~/.claude.json	否	僅在特定專案目錄內生效
project	<專案根目錄>/.mcp.json	是（提交至 git）	團隊共用，成員首次使用時會提示確認

方法一：CLI 指令

# user 層級 — 所有專案都能用
claude mcp add jira --transport http --scope user http://localhost:55522/mcp

# local 層級 — 僅目前專案（預設）
claude mcp add jira --transport http http://localhost:55522/mcp

# project 層級 — 團隊共用（會寫入 .mcp.json）
claude mcp add jira --transport http --scope project http://localhost:55522/mcp

方法二：手動編輯設定檔

user / local（~/.claude.json）：

{
  "mcpServers": {
    "jira": {
      "type": "http",
      "url": "http://localhost:55522/mcp"
    }
  }
}

project（專案根目錄 .mcp.json，提交至版本控制）：

{
  "mcpServers": {
    "jira": {
      "type": "http",
      "url": "http://localhost:55522/mcp"
    }
  }
}

其他 MCP 相容客戶端

任何支援 MCP Streamable HTTP 傳輸的客戶端皆可連線，端點為：

http://localhost:55522/mcp

致謝

原始版本由 Bob Chen 開發，後續由 Danny Chou 維護與修改。