MCP Atlassian Helm Chart 部署指南:在 Kubernetes 上运行 Jira 与 Confluence 的 MCP Server

原创2026-10-10 02:07:431,698 阅读
文章标签:MCP 服务

MCP Atlassian Helm Chart 部署指南:在 Kubernetes 上运行 Jira 与 Confluence 的 MCP Server

本指南完整讲解 mcp-atlassian 官方 Helm Chart(helm/Chart.yaml,版本 1.0.0,对应应用版本 0.20.0)的部署方式:从前提条件、快速安装、认证模式(api-token / personal-token / oauth / byot / external)、HTTP 传输与健康检查,到 OAuth Proxy + DCR、PAC/WPAD 代理、自定义客户端存储等进阶配置。读完本文,你将掌握如何在 Kubernetes 集群中生产化地部署 MCP Atlassian Server,并能依据源码与模板理解每个配置项最终如何映射为容器的环境变量与探针行为。

一、Chart 概览与部署前提

mcp-atlassian 是一个面向 Atlassian 工具链(Confluence、Jira)的 Model Context Protocol(MCP)服务器,本 Helm Chart 负责把它打包为 Kubernetes 应用,通过 Deployment、Service、ConfigMap、Secret、PVC、Ingress、HPA、RBAC 等资源一键交付。

部署前需要满足以下前提条件:

  • Kubernetes 1.19+(Chart 的 ingress.yaml 会根据集群版本自动选择 networking.k8s.io/v1、networking.k8s.io/v1beta1 或 extensions/v1beta1 API 版本)
  • Helm 3.0+
  • Atlassian Cloud 或 Server/Data Center 实例(Confluence 与 Jira 各需一个可访问的实例 URL)
  • API Token 或 OAuth 凭据(取决于所选认证模式)

Chart 元数据(helm/Chart.yaml)中 apiVersion: v2 表明采用 Helm 3 规范;默认镜像为 ghcr.io/sooperset/mcp-atlassian:0.20.0(见 helm/values.yaml 的 image 字段)。

二、安装:从快速开始到校验

1. 快速开始(Cloud + API Token)

最简方式是用 helm install 配合自定义 values 文件。官方推荐先创建一个 my-values.yaml:

# 创建 values 文件
cat > my-values.yaml <<YAML
confluence:
  url: "https://your-company.atlassian.net/wiki"
  username: "your.email@company.com"
  apiToken: "your_confluence_api_token"

jira:
  url: "https://your-company.atlassian.net"
  username: "your.email@company.com"
  apiToken: "your_jira_api_token"
YAML

# 安装 chart
helm install mcp-atlassian ./mcp-atlassian -f my-values.yaml

注意 ./mcp-atlassian 是 Chart 目录名,实际使用时应替换为你本地的 Chart 目录路径(本仓库中对应 helm 目录)。默认 authMode: "api-token"、transport: "stdio"(helm/values.yaml),因此该安装命令在默认配置下会得到一个以 stdio 模式运行、不开 HTTP 端口的 Deployment。

2. 校验 Chart 合法性

helm lint mcp-atlassian/

helm lint 会检查 Chart 结构与 values 类型是否符合规范,是 CI 中常用的前置校验步骤。

3. 干跑测试安装(dry-run)

不想写 values 文件时,可直接用 --set 逐项注入配置,并以 --dry-run --debug 预览将要生成的 Kubernetes 资源:

helm install mcp-atlassian ./mcp-atlassian \
  --set confluence.url="https://your-company.atlassian.net/wiki" \
  --set confluence.username="user@example.com" \
  --set confluence.apiToken="token" \
  --set jira.url="https://your-company.atlassian.net" \
  --set jira.username="user@example.com" \
  --set jira.apiToken="token" \
  --dry-run --debug

三、核心配置项:认证、传输与功能开关

values.yaml 是全部配置的唯一真源(完整默认值见 helm/values.yaml)。Chart 的 deployment.yaml 会把 values.yaml 中的值翻译为容器的环境变量或命令行参数,因此理解这张映射表等于理解 Chart 的全部行为。

关键配置一览

配置项 取值 说明
authMode api-token、personal-token、oauth、byot、external 认证模式,默认 api-token
transport stdio、sse、streamable-http MCP 传输方式,默认 stdio
confluence.enabled / jira.enabled true / false 启用/禁用 Confluence 或 Jira 集成
config.readOnlyMode true / false 只读模式,禁用所有写操作
persistence.enabled true / false 启用 OAuth Token 持久化(仅 OAuth 刷新流程需要)
oauthProxy.enabled true / false 暴露 MCP OAuth discovery + DCR 路由(选配,默认关闭)
oauthClientStorage.mode default / factory OAuth 客户端存储后端,default 用 FastMCP 内置存储,factory 加载自定义存储

认证模式如何映射为环境变量

从 deployment.yaml 的模板逻辑可以清楚看到认证模式的分支:

  • api-token(Cloud):注入 CONFLUENCE_USERNAME / CONFLUENCE_API_TOKEN 与 JIRA_USERNAME / JIRA_API_TOKEN,值来自 secret.yaml 生成的 Secret;
  • personal-token(Server/DC):注入 CONFLUENCE_PERSONAL_TOKEN 与 JIRA_PERSONAL_TOKEN;
  • oauth / byot(Cloud):注入 ATLASSIAN_OAUTH_CLOUD_ID;oauth 额外注入 ATLASSIAN_OAUTH_CLIENT_ID、ATLASSIAN_OAUTH_CLIENT_SECRET、ATLASSIAN_OAUTH_REDIRECT_URI、ATLASSIAN_OAUTH_SCOPE;byot 则注入 ATLASSIAN_OAUTH_ACCESS_TOKEN;
  • external:注入 ATLASSIAN_EXTERNAL_AUTH_ENABLE=true 与 IGNORE_HEADER_AUTH=true。

其中 oauth 模式下若同时启用 persistence,deployment.yaml 会挂载一个名为 oauth-tokens 的卷到 /home/app/.mcp-atlassian,用于持久化刷新后的令牌;pvc.yaml 只有在 authMode == "oauth" 且 persistence.enabled 且未指定 persistence.existingClaim 时才会创建 PVC。

传输模式决定资源形态

  • stdio(默认):不创建 Service,不暴露端口,不启用 readinessProbe(无 HTTP 服务可探测)。service.yaml 与 ingress.yaml 的模板条件均为 ne .Values.transport "stdio";
  • sse / streamable-http:自动创建 Service(默认 ClusterIP,端口 9000),容器注入 --transport <mode> --port 9000 参数与名为 http 的 containerPort,并自动挂载 readinessProbe。

常用扩展配置

confluence / jira 块还支持:

  • sslVerify:Server/DC 场景下可设为 "false" 以容忍自签名证书;
  • spacesFilter / projectsFilter:逗号分隔的 Space Key / 项目 Key,用于限定搜索范围;
  • customHeaders:逗号分隔的 key=value 自定义请求头(写入 Secret);
  • passthroughHeaders:需要透传的入站 MCP 请求头名称,逗号分隔(写入 ConfigMap)。

config 块支持 verbose、veryVerbose(对应 -v / -vv 参数)、loggingStdout(注入 MCP_LOGGING_STDOUT)与 enabledTools(逗号分隔的工具白名单,通过 --enabled-tools 传入)。所有未覆盖的变量可通过 extraEnv 追加(如用于外部认证域名白名单的 MCP_ALLOWED_URL_DOMAINS),额外的 Secret 可通过 extraSecrets 挂载。

四、外部代理认证(authMode: external)

external 模式专为"由可信网关统一鉴权"的架构设计:只有在能保证网关对每个 MCP 请求都完成认证、并覆写配置好的透传头的场景下才应使用。Chart 会为此模式自动注入 ATLASSIAN_EXTERNAL_AUTH_ENABLE 与 IGNORE_HEADER_AUTH 环境变量。

authMode: external
transport: streamable-http
jira:
  url: "https://your-company.atlassian.net"
  passthroughHeaders: "Cookie"
confluence:
  url: "https://your-company.atlassian.net/wiki"
  passthroughHeaders: "Cookie"

透传头(如 Cookie)会被当作认证信息来源。源码层面,confluence/config.py 与 jira/config.py 中均存在 ATLASSIAN_EXTERNAL_AUTH_ENABLE 的判断分支:当该变量为真时,未配置用户名/令牌也不会触发配置校验错误;utils/environment.py 同样在 Confluence 与 Jira 未完成常规配置时,把外部认证当作有效设置处理。

安全边界:如果服务地址是动态的,必须通过 extraEnv 添加 MCP_ALLOWED_URL_DOMAINS 白名单。服务器会拒绝任何不在白名单内的动态外部认证目标。

五、代理与 PAC/WPAD 自动配置

当集群 Pod 需要经企业代理访问 Atlassian 服务时,可启用 proxy 块。它支持全局代理与服务级覆盖(Confluence/Jira 各自独立):

proxy:
  enabled: true
  https: "https://proxy.example.com:8443"
  noProxy: "localhost,127.0.0.1,.internal.example.com"
  wpad:
    enabled: true
    url: "http://wpad/wpad.dat"
  jira:
    wpad:
      enabled: false
  confluence:
    wpad:
      enabled: true
      url: "http://confluence-wpad.example.com/wpad.dat"

Chart(deployment.yaml 的 Proxy 段)会据此注入:

  • HTTP_PROXY、HTTPS_PROXY、NO_PROXY、SOCKS_PROXY(全局)
  • ATLASSIAN_PROXY_WPAD_ENABLE、ATLASSIAN_PROXY_WPAD_URL(全局 WPAD)
  • CONFLUENCE_PROXY_WPAD_ENABLE、CONFLUENCE_PROXY_WPAD_URL(Confluence 级 WPAD)
  • JIRA_PROXY_WPAD_ENABLE、JIRA_PROXY_WPAD_URL(Jira 级 WPAD)
  • 以及 CONFLUENCE_HTTP_PROXY、CONFLUENCE_HTTPS_PROXY、CONFLUENCE_NO_PROXY、JIRA_HTTP_PROXY、JIRA_HTTPS_PROXY、JIRA_NO_PROXY 等服务级覆盖

注意事项:

  • proxy.wpad.enabled 是全局开关;confluence.wpad.enabled / jira.wpad.enabled 默认值为 null,设置为 true/false 可单独覆盖全局开关(模板用 ne .Values.proxy.confluence.wpad.enabled nil 判断是否注入);
  • PAC/WPAD 是选配功能,仅在未显式配置代理时才生效("only used when no explicit proxy is configured");
  • noProxy 默认值为 localhost,127.0.0.1。

六、OAuth Proxy + DCR(选配)

如需让 MCP OAuth 客户端通过 discovery 与动态客户端注册(DCR)流程接入,可启用 oauthProxy:

oauthProxy:
  enabled: true
  requireConsent: true
  allowedClientRedirectUris: "https://chatgpt.com/connector_platform_oauth_redirect,http://localhost:*"
  allowedGrantTypes: "authorization_code,refresh_token"

该配置将注入以下环境变量(deployment.yaml OAuth Proxy 段):

  • ATLASSIAN_OAUTH_PROXY_ENABLE
  • ATLASSIAN_OAUTH_REQUIRE_CONSENT
  • ATLASSIAN_OAUTH_ALLOWED_CLIENT_REDIRECT_URIS
  • ATLASSIAN_OAUTH_ALLOWED_GRANT_TYPES

其中 allowedClientRedirectUris 支持通配符(如 http://localhost:*),用于限定允许回调的客户端;allowedGrantTypes 限定 OAuth 授权类型。注意模板始终注入 ATLASSIAN_OAUTH_PROXY_ENABLE 与 ATLASSIAN_OAUTH_REQUIRE_CONSENT(值为 true/false 字符串),而两个 allowlist 仅在非空时注入。

七、自定义 OAuth 客户端存储(factory 模式)

默认 oauthClientStorage.mode: "default" 使用 FastMCP 内置的加密存储。高级部署可换用自定义存储后端工厂,且无需改动 Chart 核心 API:

oauthClientStorage:
  mode: factory
  factory:
    importPath: "my_pkg.storage:create_store"
    configJsonSecret:
      name: mcp-atlassian-storage-config
      key: config.json

它会注入:

  • ATLASSIAN_OAUTH_CLIENT_STORAGE_MODE=factory
  • ATLASSIAN_OAUTH_CLIENT_STORAGE_FACTORY(值为 importPath)
  • ATLASSIAN_OAUTH_CLIENT_STORAGE_CONFIG_JSON(可选)

配置 JSON 有两种来源:直接在 configJson 字段内联字符串,或通过 configJsonSecret.name + configJsonSecret.key 引用已存在的 Secret(模板优先使用 Secret 引用,见 deployment.yaml)。工厂可调用对象(callable)应当返回一个异步的、兼容键值存储接口的对象,供 FastMCP OAuth Proxy 客户端注册存储使用。

八、健康检查与 Readiness 探针

MCP 服务器在 HTTP 传输模式下暴露 /healthz 端点,返回 {"status": "ok"}。该端点由 servers/main.py 通过 FastMCP 自定义路由注册:

@main_mcp.custom_route("/healthz", methods=["GET"], include_in_schema=False)
async def _health_check_route(request: Request) -> JSONResponse:
    return await health_check(request)

Chart 仅在 HTTP 传输(sse 或 streamable-http)时自动把 readinessProbe 挂到容器上;stdio 模式没有 HTTP 服务,因此探针被禁用(deployment.yaml 的 if ne .Values.transport "stdio" 条件)。NOTES.txt 也明确提示:stdio 模式下无 HTTP 端点与健康检查可用。

values.yaml 中默认的探针配置:

readinessProbe:
  httpGet:
    path: /healthz
    port: http
  initialDelaySeconds: 10
  periodSeconds: 5
  timeoutSeconds: 3
  failureThreshold: 3

可按需覆盖,例如放宽检查频率与容错阈值:

readinessProbe:
  httpGet:
    path: /healthz
    port: http
  initialDelaySeconds: 15
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 5

部署完成后可手动验证:

curl http://<service-address>:9000/healthz
# 期望响应: {"status": "ok"}

九、升级与卸载

升级使用 helm upgrade,与安装共用同一份 values 文件:

helm upgrade mcp-atlassian ./mcp-atlassian -f my-values.yaml

卸载:

helm uninstall mcp-atlassian

运维提示:deployment.yaml 为 Pod 注入了 checksum/config 与 checksum/secret 注解(基于 ConfigMap 与 Secret 内容的 sha256),因此即使只修改了 values 中的配置/密钥,helm upgrade 也会触发 Pod 滚动重启,无需手动删除 Pod。

十、部署后的常用排查命令

Chart 的 NOTES.txt 在安装成功后输出以下运维命令:

# 查看 Pod 状态
kubectl get pods -n <namespace> -l "app.kubernetes.io/instance=mcp-atlassian"

# 实时日志
kubectl logs -n <namespace> -l "app.kubernetes.io/instance=mcp-atlassian" -f

# 查看 Deployment 详情
kubectl describe deployment -n <namespace> mcp-atlassian

# HTTP 模式下本地访问
kubectl port-forward -n <namespace> svc/mcp-atlassian 9000:9000
# 然后访问 http://localhost:9000

# stdio 模式下进入 Pod(适合直接集成 MCP 客户端)
kubectl exec -it -n <namespace> $(kubectl get pods -n <namespace> -l "app.kubernetes.io/name=mcp-atlassian,app.kubernetes.io/instance=<release>" -o jsonpath="{.items[0].metadata.name}") -- /bin/sh

集群内访问 HTTP 服务时,使用服务名:http://mcp-atlassian.<namespace>.svc.cluster.local:9000。

结语

MCP Atlassian Helm Chart 将"配置即声明"的思想贯彻到底:认证方式、传输协议、代理、OAuth 客户端注册与健康检查全部收敛为 values.yaml 中的结构化字段,并由 deployment.yaml 精确映射为环境变量与参数。对需要横向扩容的场景,Chart 还内置了基于 CPU/内存利用率的 HPA(hpa.yaml,默认关闭,可设置 autoscaling.enabled: true)。建议在生产环境优先采用 streamable-http + Secret 管理凭据 + 启用 readinessProbe,并按需开启 config.readOnlyMode 将 MCP 服务器限定为只读,以最小化写入风险。

登录后查看全文
mcp-atlassian