MCP Atlassian Helm Chart 部署指南:在 Kubernetes 上运行 Jira 与 Confluence 的 MCP Server
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/v1beta1API 版本) - 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_ENABLEATLASSIAN_OAUTH_REQUIRE_CONSENTATLASSIAN_OAUTH_ALLOWED_CLIENT_REDIRECT_URISATLASSIAN_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=factoryATLASSIAN_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 服务器限定为只读,以最小化写入风险。