MCP Atlassian

Model Context Protocol (MCP) server for Atlassian products (Confluence and Jira). Supports both Cloud and Server/Data Center deployments.

https://github.com/user-attachments/assets/35303504-14c6-4ae4-913b-7c25ea511c3e

<details> <summary>Confluence Demo</summary>

https://github.com/user-attachments/assets/7fe9c488-ad0c-4876-9b54-120b666bb785

</details>

本機修改版連線指南(zh-TW)

這是基於 sooperset/mcp-atlassian 的本機修改版, 額外新增 4 個 Jira 圖片/附件工具(上游沒有):

工具	用途
jira_upload_attachment	上傳附件(本機路徑或 base64)
jira_embed_image_in_description	上傳圖片並嵌入描述內文渲染,支援 append/prepend/marker 三種定位(marker 模式可把圖放進表格儲存格)
jira_add_comment_with_image	新增留言並內嵌圖片
jira_delete_attachment	刪除附件(用 attachment id 或 issue+檔名)

A. 第一次連 MCP(從零開始)

1. 取得 Jira API Token

到 https://id.atlassian.com/manage-profile/security/api-tokens 按「Create API token」, 複製產生的 token(只會顯示一次)。

2. 安裝 uv 與專案依賴

# 安裝 uv(已安裝可跳過)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 取得本專案並安裝依賴
git clone <本 repo 位址> ~/jira-mcp   # 或放任何路徑
cd ~/jira-mcp
uv sync

3. 設定 Claude Desktop

編輯設定檔(沒有就新建):

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

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uv",
      "args": [
        "--directory",
        "/你的絕對路徑/jira-mcp",
        "run",
        "mcp-atlassian"
      ],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "你的 API token"
      }
    }
  }
}

注意事項:

• --directory 後面要填本 repo 的絕對路徑(不能用 ~)
• 若 uv 不在系統 PATH,command 請填完整路徑(用 which uv 查,通常是 ~/.local/bin/uv,要展開成絕對路徑)
• token 一律放在設定檔的 env 區,不要寫進任何會 commit 的檔案
• 也要用 Confluence 的話,在 env 加上 CONFLUENCE_URL(https://your-company.atlassian.net/wiki)、CONFLUENCE_USERNAME、CONFLUENCE_API_TOKEN

4. 重啟並驗證

完全結束 Claude Desktop(macOS 按 Cmd+Q,不是只關視窗)再重開。 對 Claude 說「列出我在 Jira 的專案」,有正常回應即連線成功; 說「把某張本機圖片嵌入某張票的描述」可驗證本修改版專屬工具。

B. 從官方發佈版(uvx / Docker)切換到本修改版

如果你原本已經照官方 README 用 uvx mcp-atlassian 或 Docker 跑, 只需要改 command / args 兩個欄位,env 整段保留不動:

 {
   "mcpServers": {
     "mcp-atlassian": {
-      "command": "uvx",
-      "args": ["mcp-atlassian"],
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/你的絕對路徑/jira-mcp",
+        "run",
+        "mcp-atlassian"
+      ],
       "env": {
         "JIRA_URL": "https://your-company.atlassian.net",
         "JIRA_USERNAME": "your.email@company.com",
         "JIRA_API_TOKEN": "your_api_token"
       }
     }
   }
 }

Docker 版同理:把整個 command/args 換成上面 uv --directory ... run mcp-atlassian 的形式即可。

差異說明:

• uvx mcp-atlassian 跑的是 PyPI 上的官方發佈版,沒有本修改版的 4 個圖片/附件工具
• uv --directory <路徑> run mcp-atlassian 跑的是這個資料夾裡的原始碼,改完程式碼後重啟 Claude Desktop 就生效,不需要重新安裝
• 想換回官方版,把 command/args 改回原樣即可,隨時可逆

改完設定後一樣要完全重啟 Claude Desktop 才會生效。

---

Quick Start

1. Get Your API Token

Go to https://id.atlassian.com/manage-profile/security/api-tokens and create a token.

For Server/Data Center, use a Personal Access Token instead. See Authentication.

2. Configure Your IDE

Add to your Claude Desktop or Cursor MCP configuration:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_api_token",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_api_token"
      }
    }
  }
}

Server/Data Center users: Use JIRA_PERSONAL_TOKEN instead of JIRA_USERNAME + JIRA_API_TOKEN. See Authentication for details.

3. Start Using

Ask your AI assistant to:

• "Find issues assigned to me in PROJ project"
• "Search Confluence for onboarding docs"
• "Create a bug ticket for the login issue"
• "Update the status of PROJ-123 to Done"

Documentation

Full documentation is available at mcp-atlassian.soomiles.com.

Documentation is also available in llms.txt format, which LLMs can consume easily:

• llms.txt — documentation sitemap
• llms-full.txt — complete documentation

Topic	Description
Installation	uvx, Docker, pip, from source
Authentication	API tokens, PAT, OAuth 2.0
Configuration	IDE setup, environment variables
HTTP Transport	SSE, streamable-http, multi-user
Tools Reference	All Jira & Confluence tools
Troubleshooting	Common issues & debugging

Compatibility

Product	Deployment	Support
Confluence	Cloud	Fully supported
Confluence	Server/Data Center	Supported (v6.0+)
Jira	Cloud	Fully supported
Jira	Server/Data Center	Supported (v8.14+)

Key Tools

Jira	Confluence
jira_search - Search with JQL	confluence_search - Search with CQL
jira_get_issue - Get issue details	confluence_get_page - Get page content
jira_create_issue - Create issues	confluence_create_page - Create pages
jira_update_issue - Update issues	confluence_update_page - Update pages
jira_transition_issue - Change status	confluence_add_comment - Add comments

72 tools total — See Tools Reference for the complete list.

Security

Never share API tokens. Keep .env files secure. See SECURITY.md.

Contributing

See CONTRIBUTING.md for development setup.

License

MIT - See LICENSE. Not an official Atlassian product.