atlassian-mcp

一个用于自托管 Jira（Server / Data Center）和自托管 Bitbucket（Server / Data Center）的 Model Context Protocol (MCP) 服务器。围绕工单、拉取请求、评审线程和 git 上下文提供自然语言工作流工具。

注意： 此服务器仅支持自托管实例。Jira Cloud 和 Bitbucket Cloud 使用不同的 API，不受支持。

工具

工作流

Git

Jira

Bitbucket

自然语言示例

• "我在做什么？" → get_dev_context

• "为 FOO-123 创建分支" → start_work

• "发布这个 / 合并并关闭工单" → complete_work

• "显示等待评审的我的 PR" → bitbucket_search with mine=true

• "列出此仓库中来自 feature/ABC-123 的打开的 PR" → bitbucket_search with fromBranch

• "给我 PR 42 的完整概览" → bitbucket_get_pr

• "从当前分支向 master 打开一个 PR" → bitbucket_mutate with create

• "批准 / 合并 / 拒绝 PR 42" → bitbucket_mutate with action

• "回复 PR 42 上的评论 123" → bitbucket_comment with commentId=123

• "解决 PR 42 上的这个阻塞项" → bitbucket_comment with action=update, severity=BLOCKER, state=RESOLVED

• "列出 PR 清单任务" → bitbucket_pr_tasks with action=list

• "查找 PAY 项目中分配给我的 Bug" → jira_search with mine=true, issueType=Bug

• "当前冲刺里有什么？" → jira_search with resource=board_overview

• "将 FOO-123 移动到 In Progress" → jira_mutate with transitionName="In Progress"

• "在 FOO-123 上记录 2 小时工时" → jira_mutate with worklog

• "在 PAY 中创建版本 9.1.0" → jira_version with action=create, projectKey=PAY, name=9.1.0

• "列出 PAY 的发布" → jira_search with resource=versions, project=PAY

• "发布版本 12345" → jira_version with action=release, id=12345

• "在 FOO-123 上设置修复版本 9.1.0" → jira_mutate with update.fixVersion=9.1.0

• "在史诗 FOO-100 下创建任务" → jira_mutate with create.issueType=Task, create.parent=FOO-100（自动检测 Epic 并设置 Epic Link）

• "将 FOO-123 移动到史诗 FOO-100 下" → jira_mutate with update.epicLink=FOO-100

• "创建一个史诗" → jira_mutate with create.issueType=Epic（Epic Name 默认为摘要）

• "将故事点设置为 5" → jira_mutate with update.customFields={"Story Points": 5} — 值为纯文本（选项标签、用户名、日期、标签数组）；服务器会根据字段 schema 包装它们

• "我可以在这个工单 / 史诗上设置什么？" → jira_search resource=fields with issueKey=FOO-123（编辑界面）或 project=FOO+issueType=Epic（创建界面）：必填和可选字段、值格式、允许的值

Related MCP server: Bitbucket Server MCP

设置

1. 创建配置文件

创建 ~/.atlassian-mcp.json：

{
  "$schema": "https://raw.githubusercontent.com/stubbedev/atlassian-mcp/master/atlassian-mcp.schema.json",
  "jira": {
    "url": "https://jira.example.com",
    "token": "your-jira-personal-access-token"
  },
  "bitbucket": {
    "url": "https://bitbucket.example.com",
    "token": "your-bitbucket-personal-access-token"
  }
}

$schema 字段是可选的，但可以启用编辑器的自动补全和验证。

• projectKey 表示项目代码：

  • Jira 示例：工单 PAY-123 中的 PAY

  • Bitbucket 示例：仓库路径 ENG/payments-service 中的项目 ENG

• 你也可以使用更便捷的别名：

  • Jira：project（projectKey 的别名）

  • Bitbucket：project 和 repo（projectKey 和 repoSlug 的别名）

• 对于 Bitbucket 工具，projectKey 和 repoSlug 通常会自动从你本地的 origin 远程仓库检测。

• bitbucket_create_pull_request 还会从你当前分支自动检测 fromBranch，如果该分支已存在打开的 PR，则返回该 PR。

• Jira 项目级调用接受 projectKey，提供时效果最佳。

• 如果 Jira 问题创建/类型查找时省略了 projectKey，服务器会尝试从当前分支的工单键推断，当只有一个项目可见时回退到自动选择，否则返回带编号的项目列表供选择。

或者，使用环境变量（或此目录中的 .env 文件）：

JIRA_URL=https://jira.example.com
JIRA_ACCESS_TOKEN=your-jira-personal-access-token
BITBUCKET_URL=https://bitbucket.example.com
BITBUCKET_ACCESS_TOKEN=your-bitbucket-personal-access-token

配置按以下顺序解析：--config <path> CLI 参数 → ATLASSIAN_MCP_CONFIG 环境变量 → ~/.atlassian-mcp.json → $XDG_CONFIG_HOME/atlassian-mcp/config.json（默认 ~/.config/atlassian-mcp/config.json）→ 当前工作目录中的 .atlassian-mcp.json → 环境变量。

2. 连接到你的 AI 工具

无需克隆或构建——只需将你的工具指向 npx @stubbedev/atlassian-mcp@latest，它就会自动安装并运行。

注意：--prefer-online 可能会在某些客户端中破坏 MCP 启动。保持命令简单，需要更新时使用下面的更新步骤。

Claude Code

claude mcp add atlassian -- npx -y @stubbedev/atlassian-mcp@latest --config ~/.atlassian-mcp.json

Cursor

添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（仅项目）：

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/Users/you/.atlassian-mcp.json"]
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/Users/you/.atlassian-mcp.json"]
    }
  }
}

Zed

添加到 ~/.config/zed/settings.json：

{
  "context_servers": {
    "atlassian": {
      "command": {
        "path": "npx",
        "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"]
      }
    }
  }
}

OpenCode

添加到项目根目录的 opencode.json（或全局使用 ~/.config/opencode/opencode.json）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "atlassian": {
      "type": "local",
      "command": ["npx", "-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"]
    }
  }
}

Codex CLI

添加到 ~/.codex/config.yaml：

mcpServers:
  atlassian:
    command: npx
    args:
      - -y
      - @stubbedev/atlassian-mcp@latest
      - --config
      - /home/you/.atlassian-mcp.json

任何其他兼容 MCP 的工具

大多数支持 MCP 的工具都接受相同的 JSON 格式。使用 npx 作为命令，参数为 ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/path/to/config.json"]。

更新现有安装

如果你的 MCP 客户端已经配置好，并且你想要最新的包版本：

npx clear-npx-cache

然后重启你的 MCP 客户端。

不使用 npm 安装

服务器是一个单一的静态 Go 二进制文件。上面的 npx 路径会在首次运行时为你的平台下载预构建的二进制文件；这些替代方案完全跳过 Node：

# Go toolchain — installs to $GOBIN / $GOPATH/bin
go install github.com/stubbedev/atlassian-mcp@latest

# Nix flake
nix run github:stubbedev/atlassian-mcp -- --config ~/.atlassian-mcp.json

然后将你的 MCP 客户端的 command 指向生成的 atlassian-mcp 二进制文件，而不是 npx。在这些路径上，ffmpeg/ffprobe 必须在 PATH 中可用（或设置 ATLASSIAN_MCP_FFMPEG_PATH / ATLASSIAN_MCP_FFPROBE_PATH）；npm 包装器会自动捆绑它们。

作为 HTTP 服务器运行（共享 / 在代理后面）

默认情况下，服务器通过 stdio 进行 MCP 通信（每个客户端一个进程，由你的编辑器启动）。它也可以作为长期运行的 Streamable HTTP 服务器运行，供多个客户端共享——在反向代理后面很有用：

atlassian-mcp --http                 # binds 127.0.0.1:7337
atlassian-mcp --http 127.0.0.1:9000  # custom address
ATLASSIAN_MCP_HTTP=1 atlassian-mcp   # same, via env

• 单个端点 POST /mcp（JSON-RPC）以及可选的 GET /mcp SSE 流，用于承载服务器→客户端的请求（roots/list、elicitation）。服务器是有状态的：initialize 会创建一个会话并返回 Mcp-Session-Id 头，客户端必须在每个后续请求和 SSE 流中回显该头。带有缺失/未知/过期会话 ID 的请求会收到 HTTP 404，因此客户端会重新初始化（标准 MCP 客户端行为）。每个连接的客户端/工作树都是一个隔离的会话。

• 认证： 在回环绑定上不需要令牌。绑定非回环地址需要 ATLASSIAN_MCP_HTTP_TOKEN（客户端以 Authorization: Bearer … 形式发送）；否则服务器拒绝启动。在代理处终止 TLS。

• GET /healthz 是一个未经认证的存活探针（返回 ok），用于代理/负载均衡器。空闲会话在 1 小时后被驱逐。

仓库上下文来自客户端，而不是服务器的工作目录。 需要仓库的工具（git_* 工具、get_dev_context、start_work、complete_work 以及 Bitbucket 项目/仓库自动检测）按以下顺序解析：显式的 repoPath 参数 → 通过请求头固定的根（见下文） → 客户端的 MCP 工作区根（服务器通过 roots/list 询问，按会话缓存，并在 notifications/roots/list_changed 时刷新） → 进程 cwd（仅 stdio）。因此，一个共享的 HTTP 服务器可以处理多个工作树：每个客户端自己的工作区驱动其调用。当会话暴露多个根（多个工作树）时，没有 repoPath 的工具使用第一个 git 仓库根；传递 repoPath（绝对路径，或与某个根匹配的工作树名称/基名）以定位特定工作树。对于 Bitbucket，显式传递 projectKey+repoSlug 完全跳过仓库检测。仓库必须在服务器主机上可访问（git 工具在本地运行 git）。

通过请求头固定根（HTTP）。 已经知道工作树的反向代理或测试工具可以直接将其交给服务器，跳过 roots/list 往返（即使客户端从未通告 roots 能力也能工作）。发送 file:// URI 或绝对路径（多个用逗号分隔；第一个 git 仓库优先）：

X-Mcp-Root: file:///srv/myrepo
X-Mcp-Roots: /srv/a, /srv/b

接受的头部名称：X-Mcp-Roots、X-Mcp-Root、Mcp-Roots、Mcp-Root。头部值是权威的——它优先于 roots/list，并且在 list_changed 后仍然有效。

已运行的 HTTP 服务器的客户端配置（Claude Code 示例）：

claude mcp add --transport http atlassian http://127.0.0.1:7337/mcp

附件解码流程

附件工具（jira_get_attachment、bitbucket_get_attachment）在返回之前将二进制附件解码为模型可读的内容：

自动保存的文件会定期按 TTL 和总大小配额进行清理——请参阅下面的 环境覆盖。

外部工具（可选）

图像和 PDF 文本解码是纯 Go 实现，不需要额外的东西。没有纯 Go 实现的两个流程会调用外部二进制文件：

• ffmpeg + ffprobe — 视频和动画图像帧采样。npm 包装器捆绑了 ffmpeg-static / ffprobe-static 并注入它们的路径，因此 npx 安装路径是零配置的。在 go install / Nix 路径上，安装 ffmpeg（它提供 ffprobe）或设置下面的环境变量。

• pdftoppm（poppler）或 mutool（MuPDF） — 仅用于栅格化没有可提取文本的扫描 PDF。如果 PATH 中都没有，则此类 PDF 会保存到磁盘。

环境变量覆盖

发布（维护者）

此包以 @stubbedev/atlassian-mcp 发布到 npm。

发布使用语义化版本。破坏性工具表面更改应提升次要版本，同时保持 <1.0.0（例如 0.0.x -> 0.1.0）。

在推送 v* 标签时，.github/workflows/publish.yml 会为 14 个 OS/arch 目标交叉编译 Go 二进制文件，将它们附加到 GitHub 发布中，并发布 npm 包装器（在安装时下载匹配的二进制文件）。

发布流程：

# choose one: patch | minor | major (also: npm run release:patch / :minor / :major)
npm version patch          # bumps package.json, commits, tags vX.Y.Z
git push origin HEAD --follow-tags

flake.nix 从 package.json 读取其版本，因此 Nix 包自动跟踪相同的提升。GitHub Actions 从推送的标签构建并发布。

• 工作流配置为 npm Trusted Publisher（OIDC），因此不需要 NPM_TOKEN 密钥

必需的 npm 设置（一次性）：

• 在 npm 包设置中，将此 GitHub 仓库/工作流添加为 Trusted Publisher

创建个人访问令牌

Jira Server / Data Center

从 Jira 8.14 开始支持个人访问令牌。

1. 登录你的 Jira 实例。

2. 点击右上角的个人资料头像，然后选择 Profile。

3. 在左侧边栏中，点击 Personal Access Tokens。

4. 点击 Create token。

5. 为令牌命名（例如 atlassian-mcp），并可选择设置过期日期。

6. 点击 Create 并复制令牌——它只会显示一次。

将令牌粘贴为配置文件中 jira 下的 token 值。

如果你的 Jira 版本早于 8.14，你可以改用 HTTP Basic Auth——但此服务器仅支持 Bearer 令牌（PAT）认证。

Bitbucket Server / Data Center

从 Bitbucket Server 5.5 开始支持个人访问令牌。

1. 登录你的 Bitbucket 实例。

2. 点击右上角的个人资料头像，然后选择 Manage account。

3. 在左侧边栏的 Security 下，点击 Personal access tokens。

4. 点击 Create a token。

5. 为令牌命名（例如 atlassian-mcp）。

6. 设置权限：

   • Projects：读取

   • Repositories：读取 + 写入（创建拉取请求和添加评论需要写入权限）

7. 可选择设置过期日期。

8. 点击 Create 并复制令牌——它只会显示一次。

将令牌粘贴为配置文件中 bitbucket 下的 token 值。

开发

服务器是仓库根目录下的单个 Go 模块（没有 src/ 目录树）。

# Build the binary
go build -o atlassian-mcp .

# Run it
./atlassian-mcp --config /path/to/config.json

# Vet + unit tests
go vet ./...
go test ./...

# Test the tool list
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | ./atlassian-mcp

# Quick release smoke check (build + tools/list validation)
npm run smoke